openapi: 3.1.0
info:
title: Channable order connection order_attachments returns API
description: "# Introduction\n\nWelcome to the Channable API __v1__.\n\nThis version of the Channable API allows you to:\n\n- Access orders\n- Manage order shipments\n- Update the stock of an offer on all marketplaces\n- Access returns\n\n### Details\n\n| Key | Value\n------------- | -----------\nApi version | `v1`, `v2`\nProtocol | `HTTPS`\nHostname | `api.channable.com`\nCommon Path v1 | `/v1/companies/:company_id/projects/:project_id`\nCommon Path v2 | `/v2/companies/:company_id/projects/:project_id`\n\n\nThe Common Path is shared by all endpoints except the transporters endpoints in this version of our API. Note that you have to replace :company_id and :project_id with valid values. All endpoints using v2 will state so in their names, and should use the common path v2. All other endpoints are v1 endpoints and should use Common Path v1.\n\n## Taxonomy\n\n\n| Term | Description\n------------- | -----------\n`Platform` | A webshop platform, such as WooComerce, Lightspeed, etc.\n`Marketplace` | A place where you can sell your products, such as Amazon, Bol, eBay, etc. Sometimes referred to as _channel_.\n`Order` | A purchase of any products made by a client.\n`Offer` | A selling proposal made by a seller over any class of products. It includes price, stock and other seller-dependent values.\n\n\n## Rate Limiting\n\nThe Channable API has a rate limiting policy to which you must comply. \nIt is defined on a per-company basis, meaning that generating new API tokens will not circumvent our rate-limiting.\n\n| Frequency | Burst\n------------- | -----------\nMax 4 requests per second | Burst of 200 requests\n\n**Note**: We use the [Leaky Bucket algorithm](https://en.wikipedia.org/wiki/Leaky_bucket) for rate-limiting.\n\n## Getting started\n\n\nTo get started you need to:\n\n1. Find the project ids you are interested in\n1. Find your Channable company id\n1. Generate an **API token** for your company\n\n**Note**: Information about the supported channels can be found in our [help center](https://helpcenter.channable.com/hc/en-us/articles/360011094300-For-which-marketplaces-does-Channable-support-an-order-connection-integration-).\n\n### 1. Find your project ids\n\nTo find the project ids you are interested in:\n\n1. Log in to the Channable app\n2. Select a project\n3. Open the project `Settings`\n4. Copy the _Project id_ value\n\n\n### 2. Generate an API Token for your company\n\nTo both find your Channable `company_id` and to generate a new **API token** for your company, go to [app.channable.com](https://app.channable.com) and sign in.\n\nOn the main page navigate to company settings then channabke API.\nFrom here you can see your company id, as well as generate your API token.\n\n\n\n**Notes**:\n\n- Only owners of companies are able to generate an API Token.\n- Channable does not store your tokens. Please store them securely.\n- In case you lose or leak your token, generate a new one. The previously generated tokens can be revoked by you or will expire after 1 year.\n- Two API tokens can be valid at any time, allowing you to seamlessly change to a new token, if needed.\n\n### 3. Using the API Token\n\nYou must include your API token in every request you make to Channable. \nThe token should be included in the headers of the request: `Authorization: Bearer your_api_token`\n\n\n\nAfter generating your API token you are ready to try out the endpoints and build your integration\nusing the Channable Sandbox.\n\n**How to include the token in your requests:**\n\n```shell\n# Headers method: Authorization: Bearer\ncurl \"api_endpoint_here\"\n -H \"Authorization: Bearer your_api_token\"\n```\n\n\n### Common error codes and their meanings\n\nThe Channable API uses the following error codes:\n\nCode | Meaning | Reason\n---------- | ------- | -------\n400 | Bad Request | The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing)\n401 | Unauthorized | You are using an invalid or already revoked API token.\n403 | Forbidden | You are not allowed to access the resources your request targets.\n404 | Not Found | The targeted resources could not be found.\n405 | Method Not Allowed | You tried to access an endpoint with an invalid HTTP method.\n406 | Not Acceptable | You requested a format that isn't json.\n409 | Conflict | Your request could not be completed due to a conflict with the current state of the target resource.\n422 | Unprocessable Entity | We could understand the content type of the request entity, but we are unable to process the contained instructions.\n429 | Too Many Requests | You have sent too many requests in a given amount of time, thus exceeding our rate-limiting policy. Please try again later.\n500 | Internal Server Error | We had a problem with our server. Please try again later.\n503 | Service Unavailable | We are temporarily offline for maintenance. Please try again later.\n\n\n## Sandbox Testing\n\nThe Channable API sandbox lets you test your order integration with the Channable API in a safe\nenvironment without sending requests to the marketplaces you want to connect to. All data is mocked\nbut the structure of the data and API calls needed to manage your orders are the same no matter\nwhich marketplace you end up connecting with.\n\n\n### Setup\n\nTo set up a test environment with the Channable Sandbox you must first make a connection with the\nSandbox. This can be done in the same way as all other connections within Channable by going to\n\"Company settings\" -> \"Connections\" and clicking on \"+ Add new connection\".\n\n\n\nSelect \"Channable Sandbox\", give the connection a label and click on the blue \"Create\" button.\nNo further information is needed.\n\nOnce you have made a connection, navigate to the project you want to use and click on\n\"Setup\" -> \"Setup orders\" > \"+ Setup orders\".\n\n\n\nFrom here make an order connection between the \"Channable API\" and the \"Channable Sandbox\" and\nactivate the order connection. You are now ready to start testing.\n\n\n\n### Orders\n\nTo create a test order, navigate to \"Setup\" -> \"Orders\" -> \"Settings\" of the Channable Sandbox\norder connection.\n\n\n\nFrom here click on the gear in the top right and \"Send test order\".\n\n\n\nIn the popup fill in an item id and click the blue \"Send test order\" button. A test order has now\nbeen created, and you can use all request methods described in \"Orders\" to interact with it. If you\nneed special test cases, most data in the test order can be provided by you in the popup when you\nclick on \"Send test order\".\n\n\n### Shipments/Cancellations\n\nOnce one or more testorders have been created, use the request methods described in \"Shipment\nupdate\" and \"Cancellation update\" under \"Orders\" above to mark an order as \"shipped\" and to give it\ntrack & trace information or to mark the order as \"cancelled\".\n\n\n### Offers\n\nTo test sending offer updates, that is updating the stock value on all marketplaces that you have\nan order connection to, you can use the request methods described in \"Offers\" above. You do not need\nto have created a test order to test this as you can update the stock value of any product in your\nstore, also products that you have not received an order for through Channable.\n\n\n### Returns\n\nReturns come from the marketplaces you will connect to. In order to test this, navigate to\n\"Setup\" -> \"Setup orders\" -> \"Settings\" of the Channable Sandbox order connection. \n\n\n\nFrom here click on the gear in the top right and \"Send test return\".\n\n\n\nIn the popup fill in a Channable order id and click the blue \"Send test return\" button. A test\nreturn has now been created for the order id you filled in. You can now use all request methods\ndescribed in \"Returns\" to handle the return.\n\n\n### When you are done testing\n\nOnce you are satisfied with your Channable API setup and want to go live, contact our\nsupport department\nand they will help you setup the order connections.\n"
version: v1
x-logo:
url: https://www.channable.com/_next/image?url=https%3A%2F%2Fmedia.graphassets.com%2FcntRnbAcSrCmS1wLTWrb&w=256&q=75
tags:
- name: returns
paths:
/v1/companies/{company_id}/projects/{project_id}/returns:
get:
tags:
- returns
summary: All Returns
description: "This endpoint retrieves all returns for a given project, sorted from most recent to oldest.\nOptionally, you can pass query parameters to customize the query and response content.\n\n**Example usage**\n\nSuppose the following scenario for a given project of yours:\n - The project contains the returns `o1`, `o2`, `o3`, and `o4` (from oldest to most recent)\n - `o1` and `o4` are searchable by the term `t`\n - `o3` is searchable by the term `tE`\n\n\n| Request parameters | Response\n| ------------- | -----------\n| _none_ | `{\"returns\": [o4, o3, o2, o1], \"total\": 4}`\n| `?limit=2` | `{\"returns\": [o4, o3], \"total\": 2}`\n| `?offset=4` | `{\"returns\": [], \"total\": 0}`\n| `?offset=1` | `{\"returns\": [o3, o2, o1], \"total\": 3}`\n| `?offset=1&limit=1` | `{\"returns\": [o3], \"total\": 1}`\n| `?offset=1&limit=2` | `{\"returns\": [o3, o2], \"total\": 2}`\n| `?search=t` | `{\"returns\": [o4, o1], \"total\": 2}`\n| `?search=tE` | `{\"returns\": [o3], \"total\": 1}`\n| `?start_date=2018-01-01` | `{\"returns\": [o4, o3, o2], \"total\": 3}`\n| `?start_date=2018-01-01&end_date=2018-02-28` | `{\"returns\": [o3, o2], \"total\": 2}`\n| `?last_modified_after=2018-02-29` | `{\"returns\": [o4], \"total\": 1}`"
operationId: all_returns_companies__company_id__projects__project_id__returns_get
parameters:
- name: company_id
in: path
required: true
schema:
type: integer
title: Company Id
- name: project_id
in: path
required: true
schema:
type: integer
title: Project Id
- name: download
in: query
required: false
schema:
type: boolean
description: If true, a file download will be served
default: false
title: Download
description: If true, a file download will be served
- name: errors
in: query
required: false
schema:
type: boolean
default: false
title: Errors
- name: search
in: query
required: false
schema:
anyOf:
- type: string
minLength: 1
- type: 'null'
description: Any text based search query
title: Search
description: Any text based search query
- name: start_date
in: query
required: false
schema:
anyOf:
- type: string
format: date
- type: string
format: date-time
- type: 'null'
title: Start Date
- name: end_date
in: query
required: false
schema:
anyOf:
- type: string
format: date
- type: string
format: date-time
- type: 'null'
title: End Date
- name: retrieved_at_start
in: query
required: false
schema:
anyOf:
- type: string
format: date
- type: string
format: date-time
- type: 'null'
title: Retrieved At Start
- name: retrieved_at_end
in: query
required: false
schema:
anyOf:
- type: string
format: date
- type: string
format: date-time
- type: 'null'
title: Retrieved At End
- name: last_modified_after
in: query
required: false
schema:
anyOf:
- type: string
format: date
- type: string
format: date-time
- type: 'null'
title: Last Modified After
- name: last_modified_before
in: query
required: false
schema:
anyOf:
- type: string
format: date
- type: string
format: date-time
- type: 'null'
title: Last Modified Before
- name: limit
in: query
required: false
schema:
type: integer
maximum: 100
minimum: 1
description: Max number of results in a single page.
default: 100
title: Limit
description: Max number of results in a single page.
- name: offset
in: query
required: false
schema:
type: integer
minimum: 0
description: Filter results starting from this offset.
default: 0
title: Offset
description: Filter results starting from this offset.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RecentReturns'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/companies/{company_id}/projects/{project_id}/anonymous_returns:
get:
tags:
- returns
summary: Anonymized All Returns
description: 'This endpoint is identical to `/returns`, but the returned return data has all personal
identifiable information (PII) removed.
See the docs of `/returns` for more info on how to query this endpoint.'
operationId: anonymized_all_returns_companies__company_id__projects__project_id__anonymous_returns_get
parameters:
- name: project_id
in: path
required: true
schema:
type: integer
title: Project Id
- name: search
in: query
required: false
schema:
anyOf:
- type: string
minLength: 1
- type: 'null'
description: Any text based search query
title: Search
description: Any text based search query
- name: start_date
in: query
required: false
schema:
anyOf:
- type: string
format: date
- type: string
format: date-time
- type: 'null'
title: Start Date
- name: end_date
in: query
required: false
schema:
anyOf:
- type: string
format: date
- type: string
format: date-time
- type: 'null'
title: End Date
- name: last_modified_after
in: query
required: false
schema:
anyOf:
- type: string
format: date
- type: string
format: date-time
- type: 'null'
title: Last Modified After
- name: last_modified_before
in: query
required: false
schema:
anyOf:
- type: string
format: date
- type: string
format: date-time
- type: 'null'
title: Last Modified Before
- name: limit
in: query
required: false
schema:
type: integer
maximum: 100
minimum: 1
description: Max number of results in a single page.
default: 100
title: Limit
description: Max number of results in a single page.
- name: offset
in: query
required: false
schema:
type: integer
minimum: 0
description: Filter results starting from this offset.
default: 0
title: Offset
description: Filter results starting from this offset.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AnonymizedRecentReturns'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/companies/{company_id}/projects/{project_id}/returns/{return_id}:
get:
tags:
- returns
summary: Single Return
description: This endpoint retrieves a given return based on its id.
operationId: single_return_companies__company_id__projects__project_id__returns__return_id__get
parameters:
- name: company_id
in: path
required: true
schema:
type: integer
title: Company Id
- name: project_id
in: path
required: true
schema:
type: integer
title: Project Id
- name: return_id
in: path
required: true
schema:
type: integer
title: Return Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SingleEfferentReturn'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/companies/{company_id}/projects/{project_id}/returns/test:
post:
tags:
- returns
summary: Create Test Return
description: This endpoint allows you to create one or more test returns within Channable.
operationId: create_test_return_companies__company_id__projects__project_id__returns_test_post
parameters:
- name: project_id
in: path
required: true
schema:
type: integer
title: Project Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TestReturnBody'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/TestReturnResponse'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ChannableErrorResponse'
description: Bad Request
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ChannableErrorResponse'
description: Not Found
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/ChannableErrorResponse'
description: Conflict
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/companies/{company_id}/projects/{project_id}/returns/{return_id}/status:
post:
tags:
- returns
summary: Update Return Status
description: 'This endpoint allows you to update a return status. We will then propagate the update to
the involved marketplace.
Depending of the return status the end customer does or does not get their money back.'
operationId: update_return_status_companies__company_id__projects__project_id__returns__return_id__status_post
parameters:
- name: return_id
in: path
required: true
schema:
type: integer
title: Return Id
- name: project_id
in: path
required: true
schema:
type: integer
title: Project Id
- name: company_id
in: path
required: true
schema:
type: integer
title: Company Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ChannableReturnsPayload'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateReturnStatusResponse'
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/ChannableErrorResponse'
description: Conflict
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
SingleEfferentReturn:
properties:
return:
$ref: '#/components/schemas/EfferentReturn'
title: Return
type: object
required:
- return
title: SingleEfferentReturn
example:
return:
channel_id: '31234567'
channel_name: bol
created: '2017-02-09T12:39:48+00:00'
data:
address:
address1: streetname 1
address_supplement: ''
city: cityname
company: ''
country_code: NL
email: noreply@example.com
first_name: Firstname
house_number: '1'
house_number_ext: ''
last_name: Lastname
region_code: ''
street: streetname
zip_code: 1234 AB
customer:
email: noreply@example.com
first_name: Firstname
gender: female
last_name: Lastname
item:
comment: Some extra info
delivery_period: ''
gtin: '1234567890123'
id: 123456-some-item
quantity: 1
reason: Not as pictured
title: Product Title
meta:
channel_order_id: 123456-some-order
channel_order_id_internal: ''
channel_return_id: 123456-some-return
platform_order_id: ABC9839833
error: false
id: 1
log: []
modified: '2017-02-09T12:39:48+00:00'
obfuscated: false
platform_id: '123456'
platform_name: lightspeed
project_id: 1
retrieved_at: '2017-02-09T12:39:48+00:00'
status: new
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
AnonymizedEfferentReturnDataAddress:
properties:
city:
anyOf:
- type: string
- type: 'null'
title: City
country_code:
anyOf:
- type: string
- type: 'null'
title: Country Code
company:
anyOf:
- type: string
- type: 'null'
title: Company
region_code:
anyOf:
- type: string
- type: 'null'
title: Region Code
type: object
title: AnonymizedEfferentReturnDataAddress
ChannableReturnsPayload:
properties:
status:
$ref: '#/components/schemas/ChannableApiReturnsStatus'
type: object
required:
- status
title: ChannableReturnsPayload
description: Model for data obtained from the Channable API return status update
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
AnonymizedEfferentReturnDataCustomer:
properties:
gender:
type: string
title: Gender
type: object
required:
- gender
title: AnonymizedEfferentReturnDataCustomer
UpdateReturnStatusResponse:
properties:
status:
type: string
const: success
title: Response Status
default: success
message:
type: string
title: Message
type: object
required:
- message
title: UpdateReturnStatusResponse
ChannableApiReturnsStatus:
type: string
enum:
- accepted
- rejected
- repaired
- keeps
- exchanged
- cancelled
title: ChannableApiReturnsStatus
description: 'A container for channable api return status.
This is similar to realtime2.models.returns.ChannableReturnsStatus but is missing a few
statuses (new, manual, and processing).'
ChannableErrorResponse:
properties:
status:
type: string
const: error
title: Status
default: error
message:
type: string
title: Message
description: A description about the given error
type: object
required:
- message
title: ChannableErrorResponse
description: The standard Channable error response
ChannableReturnsDataMeta:
properties:
channel_order_id:
type: string
title: Channel Order Id
channel_order_id_internal:
anyOf:
- type: string
- type: 'null'
title: Channel Order Id Internal
platform_order_id:
anyOf:
- type: string
- type: 'null'
title: Platform Order Id
description: The same id as the 'platform_id' in the original order. For Channable api order connections 'platform_id' is the Channable order id
is_demo_return:
type: boolean
title: Is Demo Return
default: false
is_test_return:
type: boolean
title: Is Test Return
default: false
channel_return_id:
anyOf:
- type: string
- type: 'null'
title: Channel Return Id
type: object
required:
- channel_order_id
title: ChannableReturnsDataMeta
AnonymizedEfferentReturnDataItem:
properties:
id:
anyOf:
- type: string
- type: 'null'
title: Id
gtin:
anyOf:
- type: string
- type: 'null'
title: Gtin
title:
anyOf:
- type: string
- type: 'null'
title: Title
quantity:
type: integer
title: Quantity
reason:
anyOf:
- type: string
- type: 'null'
title: Reason
delivery_period:
anyOf:
- type: string
- type: 'null'
title: Delivery Period
type: object
required:
- quantity
title: AnonymizedEfferentReturnDataItem
ChannableReturnsStatus:
type: string
enum:
- new
- accepted
- rejected
- repaired
- keeps
- exchanged
- cancelled
- manual
- processing
title: ChannableReturnsStatus
description: 'A container for channable return status.
Based on the enum values of `status` column in the returns table.'
TestReturnBody:
properties:
order_id:
type: integer
title: Order Id
description: The unique id of a Channable order object.
type: object
required:
- order_id
title: TestReturnBody
ResponseModel:
properties:
status:
$ref: '#/components/schemas/ResponseModelStatus'
title: Response Status
message:
type: string
title: Message
response:
type: string
title: Response
default: ''
id:
anyOf:
- type: string
- type: 'null'
title: Id
data:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Data
description: Data relevant to the specific response. This may vary by endpoint
type: object
required:
- status
- message
title: ResponseModel
description: A container for response model.
TestReturnResponse:
properties:
status:
type: string
const: success
title: Response Status
default: success
message:
type: string
title: Message
data:
anyOf:
- items:
$ref: '#/components/schemas/ResponseModel'
type: array
- type: 'null'
title: Data
type: object
required:
- message
title: TestReturnResponse
ResponseModelStatus:
type: string
enum:
- success
- error
- warning
- debug
title: ResponseModelStatus
RecentReturns:
properties:
total:
type: integer
title: Total
error_count:
type: integer
title: Error Count
returns:
items:
$ref: '#/components/schemas/EfferentReturn'
type: array
title: Returns
type: object
required:
- total
- error_count
- returns
title: RecentReturns
example:
error_count: 0
returns:
- channel_id: '31234567'
channel_name: bol
created: '2017-02-09T12:39:48+00:00'
data:
address:
address1: streetname 1
address_supplement: ''
city: cityname
company: ''
country_code: NL
email: noreply@example.com
first_name: Firstname
house_number: '1'
house_number_ext: ''
last_name: Lastname
region_code: ''
street: streetname
zip_code: 1234 AB
customer:
email: noreply@example.com
first_name: Firstname
gender: female
last_name: Lastname
item:
comment: Some extra info
delivery_period: ''
gtin: '1234567890123'
id: 123456-some-item
quantity: 1
reason: Not as pictured
title: Product Title
meta:
channel_order_id: 123456-some-order
channel_order_id_internal: ''
channel_return_id: 123456-some-return
platform_order_id: ABC9839833
error: false
id: 1
log: []
modified: '2017-02-09T12:39:48+00:00'
obfuscated: false
platform_id: '123456'
platform_name: lightspeed
project_id: 1
retrieved_at: '2017-02-09T12:39:48+00:00'
status: new
total: 1
EfferentReturn:
properties:
id:
type: integer
title: Id
project_id:
type: integer
title: Project Id
created:
type: string
format: date-time
title: Created
modified:
type: string
format: date-time
title: Modified
retrieved_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Retrieved At
error:
type: boolean
title: Error
platform_id:
anyOf:
- type: string
- type: 'null'
title: Platform Id
platform_name:
anyOf:
- type: string
- type: 'null'
title: Platform Name
channel_id:
type: string
title: Channel Id
channel_name:
type: string
title: Channel Name
log:
items:
additionalProperties: true
type: object
type: array
title: Log
status:
$ref: '#/components/schemas/ChannableReturnsStatus'
title: Return Status
data:
additionalProperties: true
type: object
title: Data
obfuscated:
type: boolean
title: Obfuscated
type: object
required:
- id
- project_id
- created
- modified
- error
- channel_id
- channel_name
- log
- status
- data
- obfuscated
title: EfferentReturn
AnonymizedEfferentReturnData:
properties:
item:
$ref: '#/components/schemas/AnonymizedEfferentReturnDataItem'
title: Anonymized Item
address:
$ref: '#/components/schemas/AnonymizedEfferentReturnDataAddress'
title: Anonymized Address
customer:
$ref: '#/components/schemas/AnonymizedEfferentReturnDataCustomer'
title: Anonymized Customer
meta:
anyOf:
- $ref: '#/components/schemas/ChannableReturnsDataMeta'
- type: 'null'
title: Return Meta Data
type: object
required:
- item
- address
- customer
title: AnonymizedEfferentReturnData
AnonymizedRecentReturns:
properties:
total:
type: integer
title: Total
error_count:
type: integer
title: Error Count
returns:
items:
$ref: '#/components/schemas/AnonymizedEfferentReturn'
type: array
title: Anonymized Returns
type: object
required:
- total
- error_count
- returns
title: AnonymizedRecentReturns
AnonymizedEfferentReturn:
properties:
id:
type: integer
title: Id
project_id:
type: integer
title: Project Id
created:
type: string
format: date-time
title: Created
modified:
type: string
format: date-time
title: Modified
retrieved_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Retrieved At
error:
type: boolean
title: Error
platform_id:
anyOf:
- type: string
- type: 'null'
title: Platform Id
platform_name:
anyOf:
- type: string
- type: 'null'
title: Platform Name
channel_id:
type: string
title: Channel Id
channel_name:
type: string
title: Channel Name
log:
items:
additionalProperties: true
type: object
type: array
title: Log
status:
$ref: '#/components/schemas/ChannableReturnsStatus'
title: Return Status
data:
$ref: '#/components/schemas/AnonymizedEfferentReturnData'
title: Anonymized Return Data
type: object
required:
- id
- project_id
- created
- modified
- error
- channel_id
- channel_name
- log
- status
- data
title: AnonymizedEfferentReturn
description: 'A return representation from any channel to any platform,
but with all PII filtered out of the data.'
\n\n**Notes**:\n\n- Only owners of companies are able to generate an API Token.\n- Channable does not store your tokens. Please store them securely.\n- In case you lose or leak your token, generate a new one. The previously generated tokens can be revoked by you or will expire after 1 year.\n- Two API tokens can be valid at any time, allowing you to seamlessly change to a new token, if needed.\n\n### 3. Using the API Token\n\nYou must include your API token in every request you make to Channable.
\n\nSelect \"Channable Sandbox\", give the connection a label and click on the blue \"Create\" button.\nNo further information is needed.\n\nOnce you have made a connection, navigate to the project you want to use and click on\n\"Setup\" -> \"Setup orders\" > \"+ Setup orders\".\n\n
\n\nFrom here make an order connection between the \"Channable API\" and the \"Channable Sandbox\" and\nactivate the order connection. You are now ready to start testing.\n\n
\n\n### Orders\n\nTo create a test order, navigate to \"Setup\" -> \"Orders\" -> \"Settings\" of the Channable Sandbox\norder connection.\n\n
\n\nFrom here click on the gear in the top right and \"Send test order\".\n\n
\n\nIn the popup fill in an item id and click the blue \"Send test order\" button. A test order has now\nbeen created, and you can use all request methods described in \"Orders\" to interact with it. If you\nneed special test cases, most data in the test order can be provided by you in the popup when you\nclick on \"Send test order\".\n\n\n### Shipments/Cancellations\n\nOnce one or more testorders have been created, use the request methods described in \"Shipment\nupdate\" and \"Cancellation update\" under \"Orders\" above to mark an order as \"shipped\" and to give it\ntrack & trace information or to mark the order as \"cancelled\".\n\n\n### Offers\n\nTo test sending offer updates, that is updating the stock value on all marketplaces that you have\nan order connection to, you can use the request methods described in \"Offers\" above. You do not need\nto have created a test order to test this as you can update the stock value of any product in your\nstore, also products that you have not received an order for through Channable.\n\n\n### Returns\n\nReturns come from the marketplaces you will connect to. In order to test this, navigate to\n\"Setup\" -> \"Setup orders\" -> \"Settings\" of the Channable Sandbox order connection. \n\n
\n\nIn the popup fill in a Channable order id and click the blue \"Send test return\" button. A test\nreturn has now been created for the order id you filled in. You can now use all request methods\ndescribed in \"Returns\" to handle the return.\n\n\n### When you are done testing\n\nOnce you are satisfied with your Channable API setup and want to go live, contact our\nsupport department\nand they will help you setup the order connections.\n"
version: v1
x-logo:
url: https://www.channable.com/_next/image?url=https%3A%2F%2Fmedia.graphassets.com%2FcntRnbAcSrCmS1wLTWrb&w=256&q=75
tags:
- name: returns
paths:
/v1/companies/{company_id}/projects/{project_id}/returns:
get:
tags:
- returns
summary: All Returns
description: "This endpoint retrieves all returns for a given project, sorted from most recent to oldest.\nOptionally, you can pass query parameters to customize the query and response content.\n\n**Example usage**\n\nSuppose the following scenario for a given project of yours:\n - The project contains the returns `o1`, `o2`, `o3`, and `o4` (from oldest to most recent)\n - `o1` and `o4` are searchable by the term `t`\n - `o3` is searchable by the term `tE`\n\n\n| Request parameters | Response\n| ------------- | -----------\n| _none_ | `{\"returns\": [o4, o3, o2, o1], \"total\": 4}`\n| `?limit=2` | `{\"returns\": [o4, o3], \"total\": 2}`\n| `?offset=4` | `{\"returns\": [], \"total\": 0}`\n| `?offset=1` | `{\"returns\": [o3, o2, o1], \"total\": 3}`\n| `?offset=1&limit=1` | `{\"returns\": [o3], \"total\": 1}`\n| `?offset=1&limit=2` | `{\"returns\": [o3, o2], \"total\": 2}`\n| `?search=t` | `{\"returns\": [o4, o1], \"total\": 2}`\n| `?search=tE` | `{\"returns\": [o3], \"total\": 1}`\n| `?start_date=2018-01-01` | `{\"returns\": [o4, o3, o2], \"total\": 3}`\n| `?start_date=2018-01-01&end_date=2018-02-28` | `{\"returns\": [o3, o2], \"total\": 2}`\n| `?last_modified_after=2018-02-29` | `{\"returns\": [o4], \"total\": 1}`"
operationId: all_returns_companies__company_id__projects__project_id__returns_get
parameters:
- name: company_id
in: path
required: true
schema:
type: integer
title: Company Id
- name: project_id
in: path
required: true
schema:
type: integer
title: Project Id
- name: download
in: query
required: false
schema:
type: boolean
description: If true, a file download will be served
default: false
title: Download
description: If true, a file download will be served
- name: errors
in: query
required: false
schema:
type: boolean
default: false
title: Errors
- name: search
in: query
required: false
schema:
anyOf:
- type: string
minLength: 1
- type: 'null'
description: Any text based search query
title: Search
description: Any text based search query
- name: start_date
in: query
required: false
schema:
anyOf:
- type: string
format: date
- type: string
format: date-time
- type: 'null'
title: Start Date
- name: end_date
in: query
required: false
schema:
anyOf:
- type: string
format: date
- type: string
format: date-time
- type: 'null'
title: End Date
- name: retrieved_at_start
in: query
required: false
schema:
anyOf:
- type: string
format: date
- type: string
format: date-time
- type: 'null'
title: Retrieved At Start
- name: retrieved_at_end
in: query
required: false
schema:
anyOf:
- type: string
format: date
- type: string
format: date-time
- type: 'null'
title: Retrieved At End
- name: last_modified_after
in: query
required: false
schema:
anyOf:
- type: string
format: date
- type: string
format: date-time
- type: 'null'
title: Last Modified After
- name: last_modified_before
in: query
required: false
schema:
anyOf:
- type: string
format: date
- type: string
format: date-time
- type: 'null'
title: Last Modified Before
- name: limit
in: query
required: false
schema:
type: integer
maximum: 100
minimum: 1
description: Max number of results in a single page.
default: 100
title: Limit
description: Max number of results in a single page.
- name: offset
in: query
required: false
schema:
type: integer
minimum: 0
description: Filter results starting from this offset.
default: 0
title: Offset
description: Filter results starting from this offset.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RecentReturns'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/companies/{company_id}/projects/{project_id}/anonymous_returns:
get:
tags:
- returns
summary: Anonymized All Returns
description: 'This endpoint is identical to `/returns`, but the returned return data has all personal
identifiable information (PII) removed.
See the docs of `/returns` for more info on how to query this endpoint.'
operationId: anonymized_all_returns_companies__company_id__projects__project_id__anonymous_returns_get
parameters:
- name: project_id
in: path
required: true
schema:
type: integer
title: Project Id
- name: search
in: query
required: false
schema:
anyOf:
- type: string
minLength: 1
- type: 'null'
description: Any text based search query
title: Search
description: Any text based search query
- name: start_date
in: query
required: false
schema:
anyOf:
- type: string
format: date
- type: string
format: date-time
- type: 'null'
title: Start Date
- name: end_date
in: query
required: false
schema:
anyOf:
- type: string
format: date
- type: string
format: date-time
- type: 'null'
title: End Date
- name: last_modified_after
in: query
required: false
schema:
anyOf:
- type: string
format: date
- type: string
format: date-time
- type: 'null'
title: Last Modified After
- name: last_modified_before
in: query
required: false
schema:
anyOf:
- type: string
format: date
- type: string
format: date-time
- type: 'null'
title: Last Modified Before
- name: limit
in: query
required: false
schema:
type: integer
maximum: 100
minimum: 1
description: Max number of results in a single page.
default: 100
title: Limit
description: Max number of results in a single page.
- name: offset
in: query
required: false
schema:
type: integer
minimum: 0
description: Filter results starting from this offset.
default: 0
title: Offset
description: Filter results starting from this offset.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AnonymizedRecentReturns'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/companies/{company_id}/projects/{project_id}/returns/{return_id}:
get:
tags:
- returns
summary: Single Return
description: This endpoint retrieves a given return based on its id.
operationId: single_return_companies__company_id__projects__project_id__returns__return_id__get
parameters:
- name: company_id
in: path
required: true
schema:
type: integer
title: Company Id
- name: project_id
in: path
required: true
schema:
type: integer
title: Project Id
- name: return_id
in: path
required: true
schema:
type: integer
title: Return Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SingleEfferentReturn'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/companies/{company_id}/projects/{project_id}/returns/test:
post:
tags:
- returns
summary: Create Test Return
description: This endpoint allows you to create one or more test returns within Channable.
operationId: create_test_return_companies__company_id__projects__project_id__returns_test_post
parameters:
- name: project_id
in: path
required: true
schema:
type: integer
title: Project Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TestReturnBody'
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/TestReturnResponse'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ChannableErrorResponse'
description: Bad Request
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ChannableErrorResponse'
description: Not Found
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/ChannableErrorResponse'
description: Conflict
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/companies/{company_id}/projects/{project_id}/returns/{return_id}/status:
post:
tags:
- returns
summary: Update Return Status
description: 'This endpoint allows you to update a return status. We will then propagate the update to
the involved marketplace.
Depending of the return status the end customer does or does not get their money back.'
operationId: update_return_status_companies__company_id__projects__project_id__returns__return_id__status_post
parameters:
- name: return_id
in: path
required: true
schema:
type: integer
title: Return Id
- name: project_id
in: path
required: true
schema:
type: integer
title: Project Id
- name: company_id
in: path
required: true
schema:
type: integer
title: Company Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ChannableReturnsPayload'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateReturnStatusResponse'
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/ChannableErrorResponse'
description: Conflict
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
SingleEfferentReturn:
properties:
return:
$ref: '#/components/schemas/EfferentReturn'
title: Return
type: object
required:
- return
title: SingleEfferentReturn
example:
return:
channel_id: '31234567'
channel_name: bol
created: '2017-02-09T12:39:48+00:00'
data:
address:
address1: streetname 1
address_supplement: ''
city: cityname
company: ''
country_code: NL
email: noreply@example.com
first_name: Firstname
house_number: '1'
house_number_ext: ''
last_name: Lastname
region_code: ''
street: streetname
zip_code: 1234 AB
customer:
email: noreply@example.com
first_name: Firstname
gender: female
last_name: Lastname
item:
comment: Some extra info
delivery_period: ''
gtin: '1234567890123'
id: 123456-some-item
quantity: 1
reason: Not as pictured
title: Product Title
meta:
channel_order_id: 123456-some-order
channel_order_id_internal: ''
channel_return_id: 123456-some-return
platform_order_id: ABC9839833
error: false
id: 1
log: []
modified: '2017-02-09T12:39:48+00:00'
obfuscated: false
platform_id: '123456'
platform_name: lightspeed
project_id: 1
retrieved_at: '2017-02-09T12:39:48+00:00'
status: new
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
AnonymizedEfferentReturnDataAddress:
properties:
city:
anyOf:
- type: string
- type: 'null'
title: City
country_code:
anyOf:
- type: string
- type: 'null'
title: Country Code
company:
anyOf:
- type: string
- type: 'null'
title: Company
region_code:
anyOf:
- type: string
- type: 'null'
title: Region Code
type: object
title: AnonymizedEfferentReturnDataAddress
ChannableReturnsPayload:
properties:
status:
$ref: '#/components/schemas/ChannableApiReturnsStatus'
type: object
required:
- status
title: ChannableReturnsPayload
description: Model for data obtained from the Channable API return status update
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
AnonymizedEfferentReturnDataCustomer:
properties:
gender:
type: string
title: Gender
type: object
required:
- gender
title: AnonymizedEfferentReturnDataCustomer
UpdateReturnStatusResponse:
properties:
status:
type: string
const: success
title: Response Status
default: success
message:
type: string
title: Message
type: object
required:
- message
title: UpdateReturnStatusResponse
ChannableApiReturnsStatus:
type: string
enum:
- accepted
- rejected
- repaired
- keeps
- exchanged
- cancelled
title: ChannableApiReturnsStatus
description: 'A container for channable api return status.
This is similar to realtime2.models.returns.ChannableReturnsStatus but is missing a few
statuses (new, manual, and processing).'
ChannableErrorResponse:
properties:
status:
type: string
const: error
title: Status
default: error
message:
type: string
title: Message
description: A description about the given error
type: object
required:
- message
title: ChannableErrorResponse
description: The standard Channable error response
ChannableReturnsDataMeta:
properties:
channel_order_id:
type: string
title: Channel Order Id
channel_order_id_internal:
anyOf:
- type: string
- type: 'null'
title: Channel Order Id Internal
platform_order_id:
anyOf:
- type: string
- type: 'null'
title: Platform Order Id
description: The same id as the 'platform_id' in the original order. For Channable api order connections 'platform_id' is the Channable order id
is_demo_return:
type: boolean
title: Is Demo Return
default: false
is_test_return:
type: boolean
title: Is Test Return
default: false
channel_return_id:
anyOf:
- type: string
- type: 'null'
title: Channel Return Id
type: object
required:
- channel_order_id
title: ChannableReturnsDataMeta
AnonymizedEfferentReturnDataItem:
properties:
id:
anyOf:
- type: string
- type: 'null'
title: Id
gtin:
anyOf:
- type: string
- type: 'null'
title: Gtin
title:
anyOf:
- type: string
- type: 'null'
title: Title
quantity:
type: integer
title: Quantity
reason:
anyOf:
- type: string
- type: 'null'
title: Reason
delivery_period:
anyOf:
- type: string
- type: 'null'
title: Delivery Period
type: object
required:
- quantity
title: AnonymizedEfferentReturnDataItem
ChannableReturnsStatus:
type: string
enum:
- new
- accepted
- rejected
- repaired
- keeps
- exchanged
- cancelled
- manual
- processing
title: ChannableReturnsStatus
description: 'A container for channable return status.
Based on the enum values of `status` column in the returns table.'
TestReturnBody:
properties:
order_id:
type: integer
title: Order Id
description: The unique id of a Channable order object.
type: object
required:
- order_id
title: TestReturnBody
ResponseModel:
properties:
status:
$ref: '#/components/schemas/ResponseModelStatus'
title: Response Status
message:
type: string
title: Message
response:
type: string
title: Response
default: ''
id:
anyOf:
- type: string
- type: 'null'
title: Id
data:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Data
description: Data relevant to the specific response. This may vary by endpoint
type: object
required:
- status
- message
title: ResponseModel
description: A container for response model.
TestReturnResponse:
properties:
status:
type: string
const: success
title: Response Status
default: success
message:
type: string
title: Message
data:
anyOf:
- items:
$ref: '#/components/schemas/ResponseModel'
type: array
- type: 'null'
title: Data
type: object
required:
- message
title: TestReturnResponse
ResponseModelStatus:
type: string
enum:
- success
- error
- warning
- debug
title: ResponseModelStatus
RecentReturns:
properties:
total:
type: integer
title: Total
error_count:
type: integer
title: Error Count
returns:
items:
$ref: '#/components/schemas/EfferentReturn'
type: array
title: Returns
type: object
required:
- total
- error_count
- returns
title: RecentReturns
example:
error_count: 0
returns:
- channel_id: '31234567'
channel_name: bol
created: '2017-02-09T12:39:48+00:00'
data:
address:
address1: streetname 1
address_supplement: ''
city: cityname
company: ''
country_code: NL
email: noreply@example.com
first_name: Firstname
house_number: '1'
house_number_ext: ''
last_name: Lastname
region_code: ''
street: streetname
zip_code: 1234 AB
customer:
email: noreply@example.com
first_name: Firstname
gender: female
last_name: Lastname
item:
comment: Some extra info
delivery_period: ''
gtin: '1234567890123'
id: 123456-some-item
quantity: 1
reason: Not as pictured
title: Product Title
meta:
channel_order_id: 123456-some-order
channel_order_id_internal: ''
channel_return_id: 123456-some-return
platform_order_id: ABC9839833
error: false
id: 1
log: []
modified: '2017-02-09T12:39:48+00:00'
obfuscated: false
platform_id: '123456'
platform_name: lightspeed
project_id: 1
retrieved_at: '2017-02-09T12:39:48+00:00'
status: new
total: 1
EfferentReturn:
properties:
id:
type: integer
title: Id
project_id:
type: integer
title: Project Id
created:
type: string
format: date-time
title: Created
modified:
type: string
format: date-time
title: Modified
retrieved_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Retrieved At
error:
type: boolean
title: Error
platform_id:
anyOf:
- type: string
- type: 'null'
title: Platform Id
platform_name:
anyOf:
- type: string
- type: 'null'
title: Platform Name
channel_id:
type: string
title: Channel Id
channel_name:
type: string
title: Channel Name
log:
items:
additionalProperties: true
type: object
type: array
title: Log
status:
$ref: '#/components/schemas/ChannableReturnsStatus'
title: Return Status
data:
additionalProperties: true
type: object
title: Data
obfuscated:
type: boolean
title: Obfuscated
type: object
required:
- id
- project_id
- created
- modified
- error
- channel_id
- channel_name
- log
- status
- data
- obfuscated
title: EfferentReturn
AnonymizedEfferentReturnData:
properties:
item:
$ref: '#/components/schemas/AnonymizedEfferentReturnDataItem'
title: Anonymized Item
address:
$ref: '#/components/schemas/AnonymizedEfferentReturnDataAddress'
title: Anonymized Address
customer:
$ref: '#/components/schemas/AnonymizedEfferentReturnDataCustomer'
title: Anonymized Customer
meta:
anyOf:
- $ref: '#/components/schemas/ChannableReturnsDataMeta'
- type: 'null'
title: Return Meta Data
type: object
required:
- item
- address
- customer
title: AnonymizedEfferentReturnData
AnonymizedRecentReturns:
properties:
total:
type: integer
title: Total
error_count:
type: integer
title: Error Count
returns:
items:
$ref: '#/components/schemas/AnonymizedEfferentReturn'
type: array
title: Anonymized Returns
type: object
required:
- total
- error_count
- returns
title: AnonymizedRecentReturns
AnonymizedEfferentReturn:
properties:
id:
type: integer
title: Id
project_id:
type: integer
title: Project Id
created:
type: string
format: date-time
title: Created
modified:
type: string
format: date-time
title: Modified
retrieved_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Retrieved At
error:
type: boolean
title: Error
platform_id:
anyOf:
- type: string
- type: 'null'
title: Platform Id
platform_name:
anyOf:
- type: string
- type: 'null'
title: Platform Name
channel_id:
type: string
title: Channel Id
channel_name:
type: string
title: Channel Name
log:
items:
additionalProperties: true
type: object
type: array
title: Log
status:
$ref: '#/components/schemas/ChannableReturnsStatus'
title: Return Status
data:
$ref: '#/components/schemas/AnonymizedEfferentReturnData'
title: Anonymized Return Data
type: object
required:
- id
- project_id
- created
- modified
- error
- channel_id
- channel_name
- log
- status
- data
title: AnonymizedEfferentReturn
description: 'A return representation from any channel to any platform,
but with all PII filtered out of the data.'