diff --git a/pull/ankorstore/00353/public.yaml b/pull/ankorstore/00353/public.yaml new file mode 100644 index 0000000..ca5b19c --- /dev/null +++ b/pull/ankorstore/00353/public.yaml @@ -0,0 +1,10426 @@ +openapi: 3.1.0 +info: + version: 1.0.0 + title: Ankorstore Public API + description: | + Welcome to the initial release of the Ankorstore API. The documentation is a continual process so please provide feedback. + +
+ + If you found this documentation on Stoplight, please be aware this is an outdated and deprecated version! + Please update your bookmarks to [https://ankorstore.github.io/api-docs/](https://ankorstore.github.io/api-docs/) + +
+ contact: + name: Ankorstore Support + email: api@ankorstore.com + url: https://www.ankorstore.com + license: + name: CC0 1.0 Universal + url: https://creativecommons.org/publicdomain/zero/1.0/ + x-prefix: Ankorstore + x-logo: + url: https://cdn.ankorstore.com/images/logo/logo-black.svg + altText: Ankorstore + href: / +servers: + - url: https://www.public.ankorstore-sandbox.com + description: Staging Environment + - url: https://www.ankorstore.com + description: Production Environment +security: + - ProductionOAuth2ClientCredentials: [] +tags: + - name: How to work with API + description: | + ℹ️ This section provides an overview of the general concepts and conventions used throughout the API. + Also, you can find some best practices and recommendations with examples, which will help you to get started with the API. + + ### API Specification/Schema + + This API follows the [Ankorstore API Specification](https://api-spec.ankorstore.com) which is based + on the [JSON:API](https://jsonapi.org/) specification. + Please give our specification a thorough read to understand how our request and response formats work. + + ### Interacting with API + + It is recommended that you only use the resource list endpoint to retrieve newly created resource or to get + the status of top level information (e.g. such as new orders or if you have been paid yet). + Please use the single resource retrieval endpoint if you wish to fetch more information about each resource. + + ### Headers + + When making any request apart from retrieving an access token, the header `Accept: application/vnd.api+json` is required. + When sending JSON within the body of a request the header `Content-Type: application/vnd.api+json` is also required. + + 🔗 [Learn more about JSON:API media types](https://jsonapi.org/format/#jsonapi-media-type) + + ### Resource Data + + In every response, the actual resource data can be found in the root level object `data`, this will either be an array + or an object, depending on if its list based or not. + + 🔗 [Learn more about JSON:API document structure](https://jsonapi.org/format/#document-structure) + + ### Includes + + Resources may have the ability to include data from other relations in the same request. + For example, when fetching a single order you may include the retailer, the order's order items etc. + + `?include=retailer,orderItems.productOption.product` + + Includes also support nested relationships, so you can pull every order items specific product variant and base product etc. + +
+ + #### Making non-GET requests + + Includes are not just limited to `GET` requests, you may pass in these parameters for any other http method as well. + +
+ + 🔗 [Learn more about JSON:API includes](https://jsonapi.org/format/#fetching-includes) + + ### Pagination + + Ankorstore uses cursor based pagination. In the root level object for pagination supported endpoints + you will find a `meta` object containing pagination information: + + ```yaml json_schema + type: object + description: Meta + properties: + meta: + type: object + description: Meta with Pagination Details + properties: + page: + description: Cursor pagination details + type: object + properties: + from: + type: string + to: + type: string + hasMore: + type: boolean + perPage: + type: integer + ``` + + As an example: + + ```json + { + "meta": { + "page": { + "from": "63e9bacd-0288-4cf1-81ab-b34270c7f68a", + "to": "747a1dcd-decc-4f8d-a9a9-61ff4d33d92e", + "hasMore": true, + "perPage": 15 + } + } + } + ``` + + You may manually construct the pagination query parameters yourself using `page[limit]` with `page[before]` + or `page[after]` depending on which direction you wish to iterate over. + +
+ + #### Effective pagination + + We recommend using the provided helper pagination links below instead of manually constructing the URLs yourself. + +
+ + The response will also provide pagination links, so you do not need to construct these yourself: + + ```yaml json_schema + type: object + description: Links + properties: + links: + description: Pagination navigation links. If a link does not exist then you cannot paginate any further in that direction. + type: object + properties: + first: + type: string + format: url + next: + type: string + format: url + prev: + type: string + format: url + ``` + + As an example: + + ```json + { + "links": { + "first": "https://www.ankorstore.com/api/v1/orders?include=&page%5Blimit%5D=15", + "next": "https://www.ankorstore.com/api/v1/orders?include=&page%5Bafter%5D=1189606a-139e-4b4e-917c-b0c992498bad&page%5Blimit%5D=15", + "prev": "https://www.ankorstore.com/api/v1/orders?include=&page%5Bbefore%5D=e04e17bb-9e70-4ecd-a8f5-4417d45b872c&page%5Blimit%5D=15" + } + } + ``` + + 🔗 [Learn more about JSON:API pagination](https://jsonapi.org/format/#fetching-pagination) + + ### Filters + + An endpoint that supports filters requires each listed filter to be wrapped in a filter object. + E.g. you may wish to only retrieve new orders: + + `?filter[status]=ankor_confirmed` + + You may also chain filters as well: + + `?filter[status]=ankor_confirmed&filter[retailer]=1189606a-572e-4b4e-88da-b0c992498bad` + +
+ + #### What filters can be used? + + The supported filters will be listed against each endpoint in the API documentation. + +
+ + 🔗 [Learn more about JSON:API filters](https://jsonapi.org/format/#fetching-filtering) + - name: Authentication + description: | + ℹ️ The Ankorstore API uses OAuth2 authentication, in order to get a `client_id` and a `client_secret` please, + login at https://www.ankorstore.com/ and generate a new application + in the [integrations](https://ankorstore.com/account/integrations) area of your account. + +
+ + #### Testing Environment + + We recommend using the testing environment to start off with, you can find more information about it + in the [Testing API](#section/Testing-API) section. + +
+ + To generate a token pass in your `client_id` and `client_secret`: + + ```json http + { + "method": "post", + "headers": { + "accept": "application/json", + "Content-Type": "application/x-www-form-urlencoded" + }, + "baseUrl": "https://www.ankorstore.com", + "url": "/oauth/token", + "body": "grant_type=client_credentials&client_id={{client_id}}&client_secret={{client_secret}}&scope=*" + } + ``` + +
+ + #### Failing to authenticate with Postman? + + Please enable the setting `Follow Authorization Header` + + ![Postman Follow Authorization Header Setting](https://ankorstore.com/images/docs/postman-follow-authorization-header.png "Postman Follow Authorization Header Setting") + +
+ + You will receive an `access_token`: + + ```json + { + "token_type": "Bearer", + "expires_in": 3600, + "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9<...>" + } + ``` + + This access token has an expiry, in which you will receive an `401 Unauthenticated` response. To generate a new one + you can re-call the `/oauth/token` endpoint described above. + + To authenticate with every other endpoint pass in the header `Authorization: Bearer {token}`. + You can test if your token is working with this endpoint (this is a not a JSON:API based endpoint): + + ```json http + { + "method": "get", + "headers": { + "accept": "application/json", + "Authorization": "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9<...>" + }, + "baseUrl": "https://www.ankorstore.com", + "url": "/api/v1/me" + } + ``` + + If successful you will receive a 200 response: + + ```json + { + "data": { + "type": "user", + "id": 1234, + "email": "api@ankorstore.com", + "first_name": "Test", + "last_name": "Account", + "created_at": "2020-01-28T11:26:35+00:00", + "updated_at": "2022-03-15T15:23:09+00:00" + } + } + ``` + + ### Rate Limiting + + When **authenticated** (passing a valid bearer token), the rate limits are: + + - 600 requests per minute + - 24000 per hour + - 288000 per day + + Meaning you could make a consistent 200 requests per minute, every minute, all day. + + Or you could burst at up to 600 requests per minute for 40 minutes of an hour, for 12 hours of a day. + + When **unauthenticated** for endpoints that do not require authentication the rates are: + + - 120 requests per minute + - 4800 requests per hour + - 57600 requests per day + + Api responses have the following headers to help you track and manage the rate limits: + + - `X-RateLimit-Remaining`: The number of request remaining before encountering a `429 Too Many Requests` error. + - `X-RateLimit-Limit`: The number of requests allowed by the current window. + + If you exceed these rate limits then an error status code of `429 Too Many Requests` will be returned, + you will also receive the following headers: + + - `Retry-After`: The number of seconds before more attempts become available, and you could try again. + - `X-RateLimit-Reset`: A timestamp for when more attempts become available, and you could try again, specified as + seconds-since-epoch. + + The special exception to these limits the authentication endpoint `/oauth/token` which is limited to 60 requests per hour. + You should not need to authenticate more than this, if you do please get in contact with us. + - name: Available APIs + description: | + ℹ️ Following groups of endpoints are available in the current version of the API: + + - **[General](#tag/General)** - endpoints related to the general information and actions on the platform. + - **[User](#tag/User)** - endpoints related to the user management. + - **[Catalog](#tag/Catalog)** - endpoints related to the catalog management. + - **[Ordering](#tag/Ordering)** - endpoints related to the order management. + - **[Shipping](#tag/Shipping)** - endpoints related to the shipping. + - **[Fulfillment](#tag/Fulfillment)** - endpoints related to the fulfillment. + - **[Testing](#tag/Testing)** - helper endpoints for testing and data generation. + - name: Webhook Subscription + description: | + ℹ️ Ankorstore provides a mechanism of webhook notifications to notify you of events that happen on the platform. + + ### Subscribing + + There are two ways to manage your webhook subscription on the platform: + + 1. Via UI in your Ankorstore account. You can find this functionality in the `Private Apps` tab of the `Integrations` section. + 2. Directly via API. Find more details in the dedicated [Webhoooks](#tag/Webhooks) section of API specification. + + ### Format + + The webhook payload sent is the same as the resource object provided by the API. For example, if an `order.*` webhook + is fired the resource will be `OrderResource`. + + The only difference is that within the top level `meta` object you will receive an `event` object with details of the + webhook which will look like this: + + `POST https://your-webhook-url.com/webhooks/handle` + ```json + { + "meta": { + "event": { + "id": "1ecdb3d8-4cc7-64b0-81e2-0242ac140007", + "applicationId": "1ecd6935-c442-6b2c-a36b-0242ac120008", + "type": "order.brand_accepted", + "timestamp": 1653381780 + } + }, + "jsonapi": { + "version": "1.0" + }, + "data": {} + } + ``` + + ### Events + + Our currently supported events are: + + - `order.brand_created` - A new order is created for the brand + - `order.brand_accepted` - Brand accepts the order + - `order.brand_rejected` - Brand rejects the order + - `order.billing_address_updated` - Billing address is updated + - `order.shipping_address_updated` - Shipping address is updated + - `order.shipping_labels_generated` - When shipping with Ankorstore + - `order.shipped` - Fired by either shipping with custom or with Ankorstore + - `order.shipment_received` - Retailer confirms reception of the order + - `order.shipment_refused` - Retailer refuses the order + - `order.brand_paid` - Ankorstore pays the brand for the order + - `order.cancelled` - Order is cancelled + - `order.brand_accepted_reverted` - Reverted Brand accepting the order + - `order.shipping_labels_generated_reverted` - Reverted shipment labels generation, when shipping with Ankorstore + - `external_order.created` - A new external order is created for the brand + - `external_order.awaiting_fulfillment` - Order is waiting for fulfillment + - `external_order.cancelled` - Order is cancelled + - `external_order.shipped` - Order shipped from the warehouse + - `external_order.arrived` - Order is arrived and completed + + **Note:** When External Order is created webhook `external_order.created` is fired and at same time fulfillment is requested + which means `external_order.awaiting_fulfillment` is also fired. Due to async nature of webhook when you receive + these webhooks most likely order status is `awaiting_fulfillment` for `external_order.created` webhook too. + + ### Signature + + Our webhooks provide a signature so you can verify the payload hasn't been tampered with. + This signature can be found on the header `signature`. + + This is how the signature is calculated: + + ```php + /** + * @var string $payload JSON payload of the received webhook + * @var string $secret Secret key which can be found in the particular webhook subscription settings + * @var string $signature Calculated signature, to be compared with the value in the request header + */ + $signature = hash_hmac('sha256', $payload, $secret); + ``` + + You can calculate the webhook's signature and compare it to the one present in the request header. + + **Note:** the secret key needed for verification webhook signature *is not the same* as the API secret key. + Each webhook subscription has its own secret key which can be found in the particular webhook subscription settings. + + ### Retries + + If the response status code is not a `2xx` then we will retry the webhook for 5 attempts with an exponential backoff. + - name: Testing API + description: | + ℹ️ This section contains some hints and examples on how to simplify and speed up API integration process + by using our public sandbox environment for testing API. + + +
+ + To test the API you can use our public sandbox environment + [https://www.public.ankorstore-sandbox.com](https://www.public.ankorstore-sandbox.com) + +
+ + A mock server is also available as a docker image: ankorstore/api-mock-server + + `docker run --rm -t -p 1080:1080 ankorstore/api-mock-server` + + ### How to get a public sandbox account? + + #### Already live on Ankorstore? + + If your Brand is already live on Ankorstore, please try logging in with your credentials on Ankorstore public sandbox. If it does not work, please contact your Ankorstore Brand Development Manager and request an account. Once the account is created, you will receive an email with the sandbox link to set up your credentials. + + #### Not on Ankorstore yet? + + In case you are not yet live with Ankorstore, please contact our Sales Team. + + ### Using the public sandbox environment + + When you test the order management flow through the API you may want to create some dummy orders to test the API integration, to do that you can create any number of test retailer accounts on the sandbox in order to create test orders for your brand. When placing an order you can pay using the test Stripe credit card credentials below: + + Card Number: `4242 4242 4242 4242` + Expiry: `04/42` + CVV: `424` + + ### Creating test data + + Our public sandbox environment provides some endpoints to more easily generate test data. + + See the available endpoints [here](#tag/Testing). + - name: Fair Use Statement + description: | + Ankorstore provides access to its API (Application Programming Interface) for the purpose of enabling brands to integrate with our services to ease their workflow. We encourage the use of our API in accordance with the following fair use principles: + + 1. **Respect for Rate Limits**: To ensure fair access for all users, we enforce rate limits on API requests. Developers are encouraged to adhere to these limits and implement appropriate strategies, such as utilising webhooks, caching, etc. to minimize unnecessary requests and reduce load on our servers. + + 2. **Data Integrity and Privacy**: Developers must handle any data obtained through our API with care, respecting user privacy and maintaining data integrity. Any misuse or unauthorized access to user data is strictly prohibited and may result in termination of API access. + + 3. **Compliance with Terms of Service**: All usage of our API is subject to our Terms of Service. Developers are expected to review and comply with these terms, which outline the rights and responsibilities associated with using our API. + + By accessing or using our API, you agree to abide by these fair use principles and any additional terms and conditions specified in our documentation or Terms of Service. Ankorstore reserves the right to monitor API usage and take appropriate action to enforce these guidelines, including limiting or revoking access to the API for users who violate them. + + For questions or concerns regarding API usage or these fair use principles, please contact [Ankorstore Support](https://my.ankorstore.com/support/help). + - name: General + description: | + ℹ️ This section contains different general endpoints, mostly transversal for the whole system. + - name: User + description: | + ℹ️ This section describes the API endpoints which can be used for managing user-related resources. + - name: Catalog + description: | + ℹ️ This section describes the API endpoints that you can use to manage your catalog resources, such as products, product variants etc. + + ## 💡 Working with Products + + Here you will find information about the product resource and its sub-resources. If you need further information please refer to the API specification. + + ### Including Product Variants + + When retrieving the individual product via the API, you may pass an `?include=productVariants` query parameter that will return associated product variants inside the `included` root level object. + + ### Important Fields within Product Resource + + If the field contains no data, it will be `null`. + + ## 💡 Stock Management + + This API allows you to manage your product variants stock in both single- and bulk-operation mode. + There are 2 opposite options available for the stock update requests - set an explicit product quantity + or mark the corresponding product as "always in stock". + + ### Set product variant stock explicit quantity + + To set an explicit quantity for the particular product variant, you should specify the amount in the payload. + In case if the target product variant was previously marked as "always in stock", this option will be disabled and the stock + will be set to given value. + + Example of the payload to set a product variant stock to the given value (single-operation mode): + + `PATCH /api/v1/product-variants/1ed18988-6651-610e-8223-aa5cd9844f96/stock` + ```json + { + "data": { + "attributes": { + "stockQuantity": 123 + } + } + } + ``` + More details can be found in the endpoint specification + + ### Set product variant as "always in stock" + + To mark a particular product variant as "always in stock" and do not care about the stock amounts, you should include a + flag `isAlwaysInStock` into the request payload. In case if the target product variant had explicit stock amount set previously, + it will be reset. + + Example of the payload to set a product variant stock to the given value (single-operation mode): + + `PATCH /api/v1/product-variants/1ed18988-6651-610e-8223-aa5cd9844f96/stock` + ```json + { + "data": { + "attributes": { + "isAlwaysInStock": true + } + } + } + ``` + More details can be found in the endpoint specification + + ### Update stocks of multiple product variants in single request (bulk-operation mode) + + This API allows to update stocks of multiple product variants in single request. There is a specific endpoint which + accepts up to 50 operations per request. Validation, business rules and payload of each operation is identical to the + single-operation mode, described above. + + Example of the payload to update stocks of multiple product variants in single request: + + `POST /api/v1/operations` + ```json + { + "atomic:operations": [ + { + "op": "update", + "data": { + "type": "productVariants", + "id": "1ed18988-3253-610e-8223-aa5cd9844001", + "attributes": { + "isAlwaysInStock": true + } + } + }, + { + "op": "update", + "data": { + "type": "productVariants", + "id": "1ed18988-6651-610e-8223-aa5cd9844f96", + "attributes": { + "stockQuantity": 123 + } + } + } + ] + } + ``` + More details can be found in the endpoint specification + - name: Catalog Integrations + description: | + ## 👋 Getting Started + + The catalogue integration process relies on the concept of operations. An operation is a batch of records + representing the products to create, update or delete. The completion state of an operation depends + on the execution result for every record it contains. It means an operation might fail without necessarily + stopping or marking the whole operation as failed (this particular state is defined as “Partially failed”). + + - Operations can be of type `import`, `update` or `delete`. + - Only one open operation (not yet started) is allowed at a time. + - Only one operation can be performed (`started`) at a time. + - Any subsequent operation will be queued with status `pending` until previous one has finished processing. + - If no previous operation is being processed, operation will start processing right away. + + ### Operation Statuses + + The `status` attribute represents the current state of the operation, below is a table that describes each state: + + | Status | Description | + |--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + | `created` | The operation was created and not yet started. At this stage, the operation is considered open and products can still be added to the batch. | + | `skipped` | The operation is empty and was skipped (No action required). When an operation is skipped, an empty report is generated and the callback URL is called to notify operation is completed. | + | `started` | The operation started and is processing. | + | `pending` | Operation is waiting for its turn on the processing queue. The operation could not be started because another one was being processed. | + | `succeeded` | All products were successfully processed. | + | `failed` | All products failed to be processed. | + | `partially_failed` | Not all products were successfully processed. | + + ## 💡 Operation workflow + + The complete workflow for an operation occurs in 3 stages: operation creation, operation processing and reporting. + The following diagram illustrates these stages and how they are chained. + + 
+      %%{init: {"flowchart": {"curve":"basis", "htmlLabels":false, "diagramPadding":24 } } }%%
+      graph LR
+
+      created("Operation Created")
+      start("Start Processing")
+      started("Processing\nStarted")
+      succeeded(Succeeded):::success
+      skipped("Processing Skipped"):::success
+      pending("Operation pending")
+      failed(Failed):::failure
+      partial(Partially Failed):::warning
+      report("Report\nGenerated")
+      notified(Callback Sent)
+
+      subgraph creating[Creating Operation]
+      created -- Add Products --> created
+      end
+
+      created -- Start Operation --> Start{?}
+      Start -->|"Another Operation execution in progress"| pending
+      Start --->|"No other Operation in progress"| start --> E{?}
+      E -->|"Batch.size > 0"| processing
+      E --->|"Batch is empty"| skipped
+
+      subgraph processing[Processing Operation]
+      direction LR
+      started --> succeeded
+      started --> partial
+      started --> failed
+      end
+
+      succeeded --> operationCompletedActions
+      partial --> operationCompletedActions
+      failed --> operationCompletedActions
+
+      subgraph reporting[Reporting]
+      report -- Notify --> notified
+      end
+
+      subgraph triggerNext[Trigger next pending Operation]
+      end
+
+      subgraph operationCompletedActions[Post-Complete Operation Actions]
+      reporting
+      triggerNext
+      end
+
+      pending -- Wait for previous Operation to finish execution --> start
+
+      skipped -- Generate empty report --> operationCompletedActions
+
+      classDef default stroke:#4b475f,stroke-width:1px,fill:#ffffff,color:#4b475f
+      classDef success stroke:#1aae9f,stroke-width:1px,fill:#cfeeeb,color:#293845
+      classDef failure stroke:#d3455b,stroke-width:1px,fill:#f6d8dd,color:#293845
+      classDef warning stroke:#f7c325,stroke-width:1px,fill:#fdf2d1,color:#293845
+      linkStyle default stroke:#788896,stroke-width:1px,fill:transparent
+
+ + ### Creating an Operation + + The full flow of creating a complete operation consists in two steps: + + #### 1. Create a new operation + + Send a `POST` request to `/api/v1/catalog/integrations/operations` + + Example request: + ```json + { + "data": { + "type": "catalog-integration-operation", + "attributes": { + "source": "shopify", + "callbackUrl": "https://callback.url/called/after/processing", + "operationType": "import" + } + } + } + ``` + + - At this point the new operation has been created and waiting to receive products data + - Operation ID will be returned in the response payload + + #### 2. Add product data to operation + + Send a `POST` request to `/api/v1/catalog/integrations/operations/{operationId}/products` + + Products can be added only to operations with status `created`. + + If operation has been started already (having any of `started`, `pending`, `skipped`, `succeeded`, `partially_failed`, `failed`, `cancelled` status), + the request will fail with a `403 Forbidden` status code. + + Example request: + ```json + { + "products": [ + { + "id": "B006GWO5WK", + "type": "catalog-integration-product", + "attributes": { + "external_id": "B006GWO5WK", + "name": "Example product" + // ... + } + } + ] + } + ``` + + You can perform as many requests as needed to append product data during this stage. + + ### Operation Processing + + In order to start processing the operation, you have to send a `PATCH` request + to `/api/v1/catalog/integrations/operations/{operationId}` with the expected operation status (i.e. “started”). + + If there is any other operation being executed at that time, the operation will be enqueued to be processed + with the status `pending` and will be started as soon as it gets a free slot in the queue. Otherwise, the + operation will be started right away. + + Example request: + ```json + { + "data": { + "id": "90567710-de47-49e4-8536-aab80c1a469c", + "type": "catalog-integration-operation", + "attributes": { + "status": "started" + } + } + } + ``` + + ### Execution Report + + When an operation completes, an execution report is generated. + It provides the execution results (success or failure) for every product of the operation. + + You can access this report by reading from the following endpoint. + + ```http + GET /api/v1/catalog/integrations/operations/{operationId}/results + ``` + + ## 💡 Event Callbacks + + Callbacks enable you to get notified when events occur in the operation process. For example, you can + configure a callback to notify you when the operation is completed. The notification is sent via + an HTTP request to the URL you specify in the operation settings. + + Callbacks can be used to trigger automated actions in your integration. + + ### Supported events + + You can find here below the complete list of all the topics `{{resource}}.{{event}}` you can monitor: + + | Topic | Trigger | + |-------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------| + | `catalog-integration-operation.completed` | An operation reaches a completed state such as **Success**, **Failed**, or **Partially Failed** | + | `catalog-integration-operation.cancelled` | An operation was cancelled. This event is triggered when an operation processing is **Skipped** (i.e. the operation batch is empty and no action is required). | + + ### Event schema + + A callback event is represented as a JSON object and has the following properties: + + - `event` — the name of the event that occurred (e.g. “completed”) + - `topic` — the event category represented as a unique identifier of the event type. + The topic is defined as a concatenation of the resource and event names `{$.data.type}.{$.event}`, + e.g. “catalog-integration-operation.completed”. You might use this topic as a partition key to distribute + the callback events you receive to separate queues or pools of workers to process the callbacks asynchronously. + - `occurredAt` — the date and time when the event occurred + - `data` — the JSON:API resource describing the state of the entity which triggered the callback + + A callback event is delivered as a `POST` request to your endpoint. The following payload represents the notification + request that is triggered when an operation successfully completes: + + ```json + { + "event": "completed", + "topic": "catalog-integration-operation.completed", + "occurredAt": "2024-03-21T13:42:54+00:00", + "data": { + "id": "90567710-de47-49e4-8536-aab80c1a469c", + "type": "catalog-integration-operation", + "attributes": { + // ... + "status": "succeeded", + "createdAt": "2024-03-21T13:13:03+00:00", + "startedAt": "2024-03-21T13:19:32+00:00", + "completedAt": "2024-03-21T13:42:54+00:00" + // ... + } + } + } + ``` + + ### Handling callbacks + + The endpoint listening for callbacks has **3 seconds** to respond with a `2xx` (usually `200`) + response code, acknowledging a successful delivery. If the request times out or gets a response + with a status code other than `2xx`, it is considered failed. + +
+ + #### Handling webhook failures + + If a callback fails (whatever the reason) no further calls to the related endpoint are made. +
+ + ### Testing callback + + A number of websites, such as https://webhook.site and https://requestbin.com, provide free URLs that + can be used to test callbacks. Simply create a URL on one of these sites, then configure your webhook + to use it. These sites allow you to see the details of the request sent to them by the callback service. + + In addition, the Ngrok service (https://ngrok.com) allows you to tunnel callback requests to a non-publicly + accessible server, enabling you to test your callback-handling code before making it public. + + ### Operations and Drafts behaviour + + | Type | Behaviour | + |----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + | `import` | When executing an import operation existing drafts will be cleaned and new ones will be created if any of the products attached to the operation has any validation issue. | + | `update` | Will not have any impact on existing drafts. | + | `delete` | Will not have any impact on existing drafts. | + - name: Ordering + description: | + ℹ️ This section of API allows to manage different types of orders in the system. Depending on the order type, there are + different endpoints available to manage them. Before starting to work with the API, it is recommended to read the + documentation to better understand the differences between the order types, their workflow and lifecycle. + + ## 💡 General conceptions + + - _Internal Order_ - A regular type of order created via Ankorstore platform. It may have different types of shipping + and payment. + The client of such an order is always an existing retailer entity, available in Ankorstore. + - _External Order_ - A special type of order created by a brand for an external customer, which might not exist in + Ankorstore. This type of order does not expect retailer as a reference to the Ankorstore entity, but rather allows brand + to provide a custom client details, such as address, contact information etc. The orders of this type in the + current version of the platform are fulfilled by the Fulfillment Centers only and do not support any other type of shipping. + - _Master Order_ - Not a separate type of order, but rather a wrapper over other order types. + It allows to have a single reference to the order, regardless of its type. A _Master Order_ usually has a one-to-one + relationship with either _Internal Order_ or _External Order_ so either of these order can be accessed via the _Master + Order_ reference. + + ## 💡 Working with Master Orders + + ### Access different types of orders via Master Order + + As mentioned above, the _Master Order_ is a wrapper over other order types. + It allows to have a single reference to the underlying order, regardless of its type. + The available _Master Order_ endpoints allow to fetch a list of available _Master Orders_ + and also get a single _Master Order_ by its ID and, following JSON:API specification, including the + underlying orders as relations. This approach allows to deal with different order types in a unified way + (e.g. listing, pagination). However, it is still possible to access the underlying _Internal Orders_ directly, + in order to keep the backward compatibility. + + 
+      graph LR
+          A[Master Order] --> B[Internal Order]
+          A --> C[External Order]
+
+ + _Master Order_ as a standalone resource might not bring much value, but the _Master Order_ endpoints allow + to include a corresponding wrapped orders as relations, which per se contain a useful payload. + + ### Includes + + The _Master Order_ has a one-to-one relationship with either _Internal Order_ or _External Order_. Hence, + passing query parameter `?include=internalOrder`, `?include=externalOrder` or by combining different includes, + (separated by comma e.g. `?include=internalOrder,externalOrder`) you will receive wrapped order as a relation. + + For example, let's say you have only 2 orders, one of them is _Internal Order_, another is _External Order_. + If you don't include any relation into request to the [List Master Orders](#tag/Ordering/operation/list-master-orders), + + ``` + [GET] /api/v1/master-orders + ``` + + the response will contain only a list of identifiers without any wrapped orders: + + ```json5 + { + //... + "data": [ + { + "type": "master-orders", + "id": "a470c8d6-1bda-4612-b0bd-3ea2a81a9e89", + }, + { + "type": "master-orders", + "id": "0ca13de1-8e4b-4e67-a147-185cc5f6f57f", + }, + //... + ], + //... + } + ``` + + But with the inclusion of the wrapped order relations to the same endpoint + + ``` + [GET] /api/v1/master-orders?include=internalOrder,externalOrder + ``` + + the result will contain included information about the actual orders: + ```json5 + { + //... + "data": [ + { + "type": "master-orders", + "id": "a470c8d6-1bda-4612-b0bd-3ea2a81a9e89", + "relationships": { + "internalOrder": { + "data": { + "type": "internal-orders", + "id": "a470c8d6-1bda-4612-b0bd-3ea2a81a9e89" + } + }, + } + }, + { + "type": "master-orders", + "id": "0ca13de1-8e4b-4e67-a147-185cc5f6f57f", + "relationships": { + "externalOrder": { + "data": { + "type": "external-orders", + "id": "0ca13de1-8e4b-4e67-a147-185cc5f6f57f" + } + } + } + }, + //... + ], + "included": [ + { + "type": "internal-orders", + "id": "a470c8d6-1bda-4612-b0bd-3ea2a81a9e89", + "attributes": { + // Internal order attributes here + } + }, + { + "type": "master-orders", + "id": "0ca13de1-8e4b-4e67-a147-185cc5f6f57f", + "attributes": { + // External order attributes here + } + }, + //... + ] + //... + } + ``` + + To learn more about JSON:API include mechanism, please refer to the [official docs](https://jsonapi.org/format/#fetching-includes). + + ## 💡 Working with Internal Orders + + Despite the fact that the _Internal Orders_ can be accessed via the _Master Order_ endpoints, it is still possible to + access them directly, in order to keep the backward compatibility. Moreover, some actions (e.g. transiting an _Internal + Order_ to the next state) are only available via the direct _Internal Order_ endpoints. + + ### Includes + + For every endpoint that returns the _Internal Order_ resource you may pass an `?include=` query parameter + that will return extra information inside the `included` root level object. + The supported resources to include are `retailer`, `billingItems`, `orderItems`, `orderItems.productVariant` + and `orderItems.productVariant.product`. + Please note that, if you include `orderItems.productVariant` you do not need to specify `orderItems` separately. + It will be automatically included. As an example, to include all data possible you would + do `?include=retailer,billingItems,orderItems.productVariant.product` + +
+ + #### Product options usage is deprecated + + Please note, that we have fully completed migrating our system to the new product model with product options + replaced by product variants. It means, the usage of product options is deprecated and will be removed in the future + versions of the API. + + Please, consider updating your API clients in favor of using `orderItems.productVariant` instead of `orderItems.productOption` + to avoid any issues in the future. For the time being, the API still supports both approaches, but we strongly encourage + you to not rely on the deprecated resources anymore because we cannot fully guarantee their stability due to some technical limitations. + +
+ + ### Important Fields within Internal Order resource + + If the field contains no data, it will be `null`. The only exception currently to this is `shippingOverview` which can + be viewed below. The fields listed below are not all the fields, please see the API specification for all of them. + + ### Status `status` + + The status field is the current state of the order, below is a table that describes each step: + + | Status | Description | + |-----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + | `ankor_confirmed` | The order has been confirmed by Ankorstore and now a decision can be made whether to accept or reject this order. | + | `rejected` | The order has been rejected, Ankorstore needs to approve this rejection. If it does, the status will moved to `cancelled`. | + | `brand_confirmed` | The order has been accepted. it now needs to be shipped to the retailer. | + | `shipping_labels_generated` | The order has been shipped with Ankorstore and the labels have been generated - these are now available in the order resource data within `shippingOverview`. | + | `fulfillment_requested` | The brand has chosen to fulfill the order, or the order was automatically fulfilled. The order will remain in this state until it has been fulfilled by the fulfillment provider. | + | `shipped` | The order has either been picked up by an Ankorstore carrier (e.g UPS) or the brand has chosen to ship with their own carrier. | + | `received` | The retailer has received the package, if shipped with Ankorstore this is automatic from the carrier otherwise for custom shipping the retailer has to manually acknowledge this. | + | `reception_refused` | The retailer has refused the reception of the package - if Ankorstore approves the reason the order will move to cancelled. The status can also move to `received` if the retailers issues have been resolved by the brand or Ankorstore. | + | `invoiced` | The final invoice has been issued for this order. | + | `brand_paid` | The brand has been paid in full for this order. | + | `cancelled` | The order is cancelled. | + + 
+      flowchart LR
+          ankor_confirmed -- accept order -->brand_confirmed
+          ankor_confirmed -- reject order -->rejected-->cancelled
+          brand_confirmed -- shipping method: custom -->shipped
+          brand_confirmed -- shipping method: ankorstore -->shipping_labels_generated
+          brand_confirmed -- shipping method: fulfillment -->fulfillment_requested
+          shipping_labels_generated-->shipped
+          fulfillment_requested-->shipped
+          shipped-->reception_refused-->cancelled
+          shipped-->received-->invoiced-->brand_paid
+          reception_refused-->received
+
+ +
+ + #### Not to be confused: Status vs Shipping Flow + + The above diagram shows what status the order will be in **based** on the actions performed in the API. The most + confusing may be the shipping flow. To reach the `shipped` or `shipping_labels_generated` status, a shipping quote must + always be generated and then confirmed. Please see [shipping an order](#tag/Order/Shipping-an-Order) for further + details. + +
+ + ### Shipping Method `shippingMethod` + + What shipment method has been chosen for this order. Either `ankorstore` for using Ankorstore's shipping service, + `custom` for using the brand's own carrier or `fulfillment` if the order is shipped from a fulfillment centre + This field is `null` when no choice has yet been made. + + ### Shipping Overview `shippingOverview` + +
+ + #### Field Availability + + The object `shippingOverview` is only available when retrieving a single order. This data is not available when + retrieving a list of orders. + +
+ + ### Submitted At `submittedAt` + + This is the date the retailer submitted their whole order. + + ### Shipped At `shippedAt` + + This is when the brand shipped the order. + + ### Brand Paid At `brandPaidAt` + + This is when Ankorstore pays the brand, if it is `null` then payment is still pending. + + ### Interacting with Internal Orders + + When a brand receives a new order, it arrives in the `ankor_confirmed` status. The brand can then perform certain + transitions using a single endpoint: + + `POST /api/v1/orders/{id}/-actions/transition` + + This endpoint will accept different payloads depending on what transition is provided. This page will detail each + transition that may be performed and when. + + All the implementation details and fields can be found in the endpoint documentation. + +
+ + #### No going back! + + Once an order is accepted or rejected it cannot be reversed. If this was a mistake the brand can contact Ankorstore + through the normal channels to revert the order to `ankor_confirmed`. + +
+ + If an order is rejected you need to provide a detailed reject reason. Otherwise, after the order is accepted the brand + then needs to ship it. + Please see [shipping](#tag/Shipping) for further details. + + ### Accepting an Internal Order + + Can be performed when the order is in `ankor_confirmed`. + + In order to accept an order without any item modifications a simple payload detailing the transition will suffice: + + ```json + { + "data": { + "type": "brand-validates" + } + } + ``` + + The order will move from `ankor_confirmed` to `brand_confirmed`. + + ### Accepting an Internal Order with modifications + + Can be performed when the order is in `ankor_confirmed`. + + Sometimes you may wish to modify the order before accepting it if for example you do not have the items in stock or + further communication has taken place with the retailer. + + The order items can **only be modified at this stage**. The rules of the payload are as follows: + + - To leave an item's quantity as is, do not include it in the payload below + - To update an item's quantity, include it in the payload below with the new quantity (cannot be above the current + quantity) + - To remove an item entirely, set the item's quantity to 0. + + You cannot remove all items, please reject the order in this scenario. + + ```json + { + "data": { + "type": "brand-validates", + "attributes": { + "orderItems": [ + { + "id": "a470c8d6-1bda-4612-b0bd-3ea2a81a9e89", + "type": "order-items", + "attributes": { + "quantity": 12 + } + }, + { + "id": "0ca13de1-8e4b-4e67-a147-185cc5f6f57f", + "type": "order-items", + "attributes": { + "quantity": 0 + } + } + ] + } + } + } + ``` + + The order will move from `ankor_confirmed` to `brand_confirmed`. + + ### Rejecting an Internal Order + + Can be performed when the order is in `ankor_confirmed`. + + To reject an order you must provide a reason listed below for the `rejectType` field. + + - `BRAND_ALREADY_HAS_CUSTOMER_IN_THE_AREA` - Brand already has a customer in the area + - `BRAND_CANNOT_DELIVER_TO_THE_AREA` - Brand cannot make a delivery to the target area + - `BRAND_HAS_EXCLUSIVE_DISTRIBUTOR_IN_THE_REGION` - The brand already has an exclusive distributor in the target region + - `BUYER_NOT_A_RETAILER` - The buyer does not seem to be a retailer + - `ORDER_ITEMS_PRICES_INCORRECT` - The prices of items in this order were incorrect + - `PAYMENT_ISSUES_WITH_RETAILER` - Brand had payment issues in the past with this retailer + - `PREPARATION_TIME_TOO_HIGH` - The time needed for the order preparation is excessively high + - `PRODUCT_OUT_OF_STOCK` - Order cannot be processed because one or multiple ordered products are not in the stock + - `PURCHASE_NOT_FOR_RESALE` - This purchase does not seem to be for resale + - `RETAILER_AGREED_TO_DO_CHANGES_TO_ORDER` - The retailer agreed so that they can do changes to the order + - `RETAILER_NOT_GOOD_FIT_FOR_BRAND` - The retailer who made an order does not fit the brand's criteria + - `RETAILER_VAT_NUMBER_MISSING` - The retailer VAT number is missing + + + - `OTHER` - If no reason above is suitable you can use value, but you **MUST** provide a `rejectReason` which accepts a + plain text string of 1000 characters. + + ### Example rejection + + ```json + { + "data": { + "type": "brand-rejects", + "attributes": { + "rejectType": "ORDER_ITEMS_PRICES_INCORRECT" + } + } + } + ``` + + ### Example rejection with OTHER + + ```json + { + "data": { + "type": "brand-rejects", + "attributes": { + "rejectType": "OTHER", + "rejectReason": "a different reason" + } + } + } + ``` + + The order will move from `ankor_confirmed` to `cancelled`. + + ### Resetting an Internal Order's generated shipping labels + + Can be performed when the order is in `shipping_labels_generated`. + + To reject an order you must provide a reason listed below for the `resetType` field. + + - `BRAND_NEED_MORE_LABELS_TO_SHIP` - Brand needs more shipping labels to ship + - `BRAND_PUT_WRONG_WEIGHT_DIMENSIONS` - Brand put wrong parcel weight and/or dimensions + - `BRAND_SHIPS_WITH_DIFFERENT_CARRIER` - Brand wants to ship with a different carrier + - `PROBLEM_DURING_SHIPPING_LABEL_GENERATION` - There was a problem during the shipping labels generation + - `RETAILER_ASKED_DELIVERY_ADDRESS_CHANGE` - The retailer asked for a delivery address change + - `SHIPPING_ADDRESS_MISMATCHES_PICKUP_ADDRESS` - The shipping address mismatches the pickup address + + + - `OTHER` - If no reason above is suitable you can use this value, but you **MUST** provide a `reason` which accepts a + plain text string of 300 characters maximum. + + #### Example reset shipping labels + + ```json + { + "data": { + "type": "brand-resets-shipping-labels-generation", + "attributes": { + "resetType": "BRAND_PUT_WRONG_WEIGHT_DIMENSIONS" + } + } + } + ``` + + #### Example reset shipping labels with OTHER + + ```json + { + "data": { + "type": "brand-resets-shipping-labels-generation", + "attributes": { + "rejectType": "OTHER", + "reason": "a different reason" + } + } + } + ``` + + The order will move from `shipping_labels_generated` to `brand_confirmed`. + + ### Requesting fulfillment by Ankorstore Logistics for an Internal Order + + Can be performed when the order is in `brand_confirmed`. + + Ankorstore Logistics will fulfill the order and ship it to the retailer. + The order will move from `brand_confirmed` to `fulfillment_requested`. + + Must be preceded by a [fulfillability check](#tag/Ordering/operation/internal-order-is-fulfillable), since it requires + the brand to be enrolled with Ankorstore logistics, and sufficient stock to be available in an Ankorstore warehouse. + + Validation errors can include: + - `not_a_fulfillment_brand` - The brand is not enrolled with Ankorstore Logistics + - `unavailable_items` - One or more items are not available in the warehouse. The response will include a list of the + unavailable items, which map to` productVariant.fulfillableId` + - `already_being_fulfilled` - The order is already being fulfilled + - `not_available_for_international_orders` - Fulfillment is currently not available for orders crossing a customs border + - `stock_is_being_transferred` - The stock is currently being transferred between warehouses + + ### Available operations on Internal Orders + + - [List Internal Orders](#tag/Ordering/operation/list-internal-orders) + - [Retrieve a single Internal Order](#tag/Ordering/operation/get-internal-order) + - [Transition an Internal Order](#tag/Ordering/operation/transition-internal-order) - accept, reject order etc. + - [List shipping quotes](#tag/Shipping/operation/list-order-shipping-quotes) - get a list of shipping quotes for a given order + - [Confirm shipping quote](#tag/Shipping/operation/confirm-order-shipping-quote) - confirm the shipping quote and move the order into its shipping phase + - [Schedule pickup for order](#tag/Shipping/operation/ship-internal-order-schedule-pickup) - schedule a pickup for the order (if shipped with Ankorstore) + - [Ship order with custom](#tag/Shipping/operation/ship-internal-order-custom) - generate a quote for shipping with your own carrier + - [Check fulfillability](#tag/Ordering/operation/internal-order-is-fulfillable) - check whether an order is fulfillable by Ankorstore Logistics + + You can also find some details about shipping in the dedicated [Shipping](#tag/Shipping) section, + + ## 💡 Working with External Orders + + The information about _External Orders_ can be only listed and retrieved as a relation of _Master Order_ endpoints. + However, some _External Order_-specific operations are also available, see the section below. + + ### How to create External Order? + + The creation of _External Order_ is as easy as just sending one request to the API. + The process of creation is asynchronous, because it involves some 3rd party services, such as Fulfillment Center + operators, who needs to confirm the possibility of fulfillment (availability of the stock, etc.). + + For better understanding, you can treat the creation of _External Order_ an "intent to create an order with particular items for + particular client". So after submission, the intent is either accepted or rejected by API, depending on the different + factors (such as availability of the stock, etc.). More on this below. + + #### Preparing for External Order creation + + Usually, before sending the actual `Create External Order` request, you need collect some information in order to make the request valid. + + The request payload is described in details in the [endpoint specification](#tag/Ordering/operation/ordering-create-non-ankorstore-fulfillment-order) + but here we will take a general look at the necessary pieces of the information required for the request: + + 1. **Valid set of fulfillables.** The endpoint accepts the list of [fulfillable items](#tag/Fulfillment/About-Fulfillment). + The identifiers should be valid and the quantities should be evenly divisible by the batch size. Otherwise, the + request might be rejected by the API. + 2. **Valid shipping address.** This is one of the most important parts of the order, please make sure the address is + completely valid, the provided postal code and phone number match the specified country etc. Otherwise, any mistake + in the address fields could be only fixed with the help of the Ankorstore Support team. + 3. **Generate unique identifier (UUID) for the order.** Despite this field is optional, considering the asynchronous + nature of the process, it is highly recommended to provide it. This will allow you to immediately get the information + about the order, check its status etc. Omitting this field will result in the generation of the identifier by API + and will only make sense if you don't want to check the result immediately ("fire-and-forget"). + + The last 2 steps can be done independently, but the first step is a bit more complicated, because it requires the knowledge + about the available products and their identifiers. This information can be obtained via the [Catalog API](#tag/Products) + and [Fulfillment API](#tag/Fulfillment). + + ### A practical example + +
+ + The assumption here is that you already authenticated and able to access the API. + If not, please follow the [Authentication](#tag/Authentication) section first. + +
+ + Here is an example of the real use-case for the External Order creation. + Let's say, you'd like to create an order for the following client: + + | Field | Value | + |--------------|-------------------------------------------| + | Client name | John Doe | + | Company name | ACME | + | Phone | +33 612345678 | + | Email | john@acme.com | + | Address | 123, Rue de Foo Bar, Paris, 75001, France | + + with the following content: + + | Product SKU | Quantity | + |-------------|----------| + | AB-1234 | 12 | + | CD-00-XY | 5 | + + In this scenario, you should take the following steps: + + #### [1] Find the fulfillable identifiers for the given products + + This can be achieved by sending a request to the [List Product Variants](#tag/Catalog/operation/list-product-variants-with-stock) + + ``` + [GET] /api/v1/product-variants?filter[sku]=AB-1234,CD-00-XY + ``` + + and finding the fulfillable identifiers for the desired products. + + As a result of this step, you should have the following information: + + | Product SKU | Quantity | Fulfillable ID | + |-------------|----------|--------------------------------------| + | AB-1234 | 12 | 1ac37dbf-f25d-4c0c-bcc8-ad8af946b541 | + | CD-00-XY | 5 | e5e91243-d11a-47a3-9308-22af70da5bc4 | + + #### [2] Find the information about the available stocks for the products + + This information can be retrieved by sending a request to [List Fulfillable Endpoint](#tag/Fulfillment/operation/fulfillment-list-fulfillable). + With the fulfillable identifiers from the previous step, you can send the following request: + + ``` + [GET] /api/v1/fulfillment/fulfillable?fulfillableIds[]=1ac37dbf-f25d-4c0c-bcc8-ad8af946b541&=fulfillableIds[]=e5e91243-d11a-47a3-9308-22af70da5bc4 + ``` + + and get quantity information for the given fulfillables from the response. + + For each requested fulfillable item, the response of this endpoint contains 2 properties: + + - `unitQuantity` - the total available quantity of the product, in minimal atomic units (e.g. bottles) + - `batchQuantity` - the total available quantity of the batches (packs) of the product (e.g. boxes of bottles) + + Having these 2 properties, you should check 2 things, before move on: + + 1. The planned quantity for the corresponding product in the order should not exceed `unitQuantity` from the response. + If the requested quantity is greater than the `unitQuantity`, the request will be rejected. + 2. The requested quantity of the product should be evenly divisible by the "batchSize", which can be calculated + by dividing returned `unitQuantity` by the `batchQuantity`. This is required because the Fulfillment Center can only + fulfill products by the whole batches (packs). Violating this rule will result in the rejection of the request. + + After these simply calculations, you should end up with the following information: + + | Product SKU | Quantity | Fulfillable ID | Batch Size | + |-------------|----------|--------------------------------------|------------| + | AB-1234 | 12 | 1ac37dbf-f25d-4c0c-bcc8-ad8af946b541 | 3 | + | CD-00-XY | 5 | e5e91243-d11a-47a3-9308-22af70da5bc4 | 5 | + + as you can see here, the quantities are evenly divisible by the batch sizes, which means the products information is + ready to go. For instance, the products from our example will be fulfilled by 4 packs of `AB-1234` and 1 pack of `CD-00-XY`. + + #### [3] Validate the shipping address + + The next step is to validate the shipping address. As it was mentioned before, the address properties should + correspond to each other and be valid. + + So the user information in this example looks valid and the only thing left is to distribute the address fields + to the corresponding properties: + ```json5 + { + "country": "FR", // ISO 3166-1 alpha-2 country code + "postalCode": "75001", // Valid postal code for France + "city": "Paris", + "street": "123, Rue de Foo Bar", // 60 characters max, otherwise will not fit the place on the printed label + "company": "ACME", + "firstName": "John", + "lastName": "Doe", + "phone": "+33 612345678", // Valid phone number for France + "email": "john@acme.com" + } + + ``` + + #### [4] Generate unique identifier for the order + + The next step is to generate UUID (preferably [UUIDv6](https://www.ietf.org/archive/id/draft-peabody-dispatch-new-uuid-format-04.html#name-uuid-version-6)) for the order being created. + You can use any library of your choice to generate it, the only requirement is that it should follow the specification. + + #### [5] Send the request to the API + + At this point, you are ready to send the request to the API. What is left to do is to prepare API request payload by putting + together all the information collected in the previous steps. For the exact payload structure, please refer to the + [endpoint specification](#tag/Ordering/operation/ordering-create-non-ankorstore-fulfillment-order). + + The successful acceptance of the request does not mean 100% guarantee that the order will be fulfilled by Fulfillment + Centre. The validation on the Fulfillment Centre side is usually taking some time, so you should check the status of + the order by sending request to the [Get Master Order](#tag/Ordering/operation/get-master-order) endpoint, using the + generated UUID as an identifier and including the `externalOrder` relation. The status of the included _External Order_ + will indicate the actual status of the order. + + ## ⚠️ Deprecation notice + +
+ + Some of the endpoints and documents from this section are deprecated and will be removed in the future. + You can temporarily still find them [here](#tag/Deprecated). + +
+ - name: Shipping + description: | + ℹ️ Here your can find endpoints related to different types of shipping, available on the platform. + +
+ + Please note, that shipping information described here is only available for _Internal Orders_. + For more details check the [Orders](#tag/Ordering/General-conceptions) section. + +
+ + ## 💡 How to ship an Internal Order? + + When shipping with either method `ankorstore` or `custom` the brand must provide the parcel data it intends + to ship the products in. This parcel information is required when generating quote with either shipping method: + + - For custom method : + - Get the quote : `/v1/orders/:orderId/ship/custom` + + - For ankorstore method : + - Get quote list : `/v1/orders/:orderId/shipping-quotes` + + Once the quote is generated, the brand must confirm the selected one by calling : + - For custom method : + - Confirm shipping : `/v1/shipping-quotes/:quoteId/confirm` + + - For ankorstore method : + - Confirm shipping : `/v1/shipping-quotes/:quoteId/confirm` + +
+ + #### What is the difference between the 2 methods? + + **Ankorstore** : For this option, Ankorstore will pre-select the best carrier option for you after you’ve entered + the parcel weight and size based on a competitive quotation offer. + + Once the offer is selected a label will be generated and available in order payload + + **Custom** : With this option, you use your preferred carrier and get a reimbursement from us based on our freight costs. + + To find out more about Ankorstore's shipping options, please [visit our FAQs.](https://ankorstoresas.my.site.com/faq/s/article/what-shipping-options-are-available-with-ankorstore?language=en_US) + +
+ + The brand can generate many quotes between both providers or a single one with different parcel configurations + before they decide to **confirm** the quote. An example flow: + + 
+      flowchart LR
+          A[Start] --> B[I want to ship with Ankorstore]
+          B --> B.1[Get shipping quote list: 
 orders/:orderId/shipping-quotes]
+          B.1 --> B.2{Is the shipping list empty ?}
+          B.2 -- NO --> B.YES[I'm happy with at least one proposed quote]
+          B.2 -- YES --> B.NO[I can consider to ship with my custom solution]
+          B.YES --> D[I Confirm the quote: 
 shipping-quotes/:quoteId/confirm]
+          B.NO --> A
+          A[Start] --> C[I want to ship with custom: 
 orders/:orderId/ship/custom]
+          C --> C.1[Get the quote]
+          C.1 --> D
+
+ + ### Shipping Methods + + Within the `shippingOverview` object, there is a field that holds the supported shipping methods for an order: + + ```json + { + "status": "brand_confirmed", + ... + "shippingOverview": { + "availableShppingMethods": ["custom", "ankorstore"] + } + } + ``` + + Please check this before attempting to ship with ankorstore as it may not be available. + +
+ + #### Parcels + + On either shipping method, if the brand has previously generated a quote and is now generating a new one + the full list of parcels must be provided. The quote endpoint **cannot** be called with an empty parcel list + to re-use the old parcel data. + +
+ +
+ + #### Confirming a quote + + To confirm a quote, the ID must be provided when calling the `/v1/shipping-quotes/:quoteId/confirm` endpoint. + +
+ + Apart from `shippingMethod` that is at the order resource level, all information regarding shipping and tracking + is stored within the `shippingOverview` object. This includes the `latestQuote` generated and the `shippingCostsOverview`. + + ## 💡 Shipping Costs Overview + +
+ + We advise you to pay attention on the shippingCostsOverview object, especially when type=fee as the amount referenced + here will be subtracted from the brandTotalAmount. + +
+ + In the `latestQuote` object, an object called `shippingCostsOverview` might appear depending on the shipping method selected. + This object includes the cost of the shipping and the type of the cost : + + Fee payload example : + + ```json + { + "shippingCostsOverview": { + "amount": 5160, + "currency": "EUR", + "type": "fee" + } + } + ``` + + Refund payload example : + + ```json + { + "shippingCostsOverview": { + "amount": 1060, + "currency": "EUR", + "type": "refund" + } + } + ``` + + If the type is **fee**, it means that this amount will be subtracted from brand net amount as a contribution + to shipping costs. If the type is **refund**, the amount will be refunded to the brand. + + In the new endpoint for listing quotes `v1/orders/:orderId/shipping-quotes`, the shipping cost of the selected + quote will be the fee subtracted from total amount (here 8.07 euros): + ```json + { + "quoteUuid": "1edd47df-b91a-68b0-b517-52e73cd28d4f", + "carrierCode": "ups", + "serviceCode": "11", + "serviceCommercialName": "UPS Standard", + "collectionMethod": [ + "pickup", + "drop-off" + ], + "shippingCost": { + "amount": 807, + "currency": "EUR" + } + } + ``` + +
+ + #### Want more information about shipping contribution? + + To find out more about Ankorstore's contribution to your shipping costs, please [visit our FAQs.](https://knowledgecommunity.force.com/faq/s/article/shippingpolicy?language=en_US) + +
+ + ### Shipping with the brands own carrier + + The quote action will return an amount that will be refunded back to the brand based on the shipping grid refund matrix. + + The confirm action is synchronous, meaning when the action is called the order resource will have its status + changed to `shipped` upon returning a response. It is up to brand to provide tracking details for the retailer when calling this action. + + 
+      sequenceDiagram
+
+        participant O as Order
+        participant SWC as Ship : 
 orders/:orderId/ship/custom
+        participant SC as Confirm : 
 shipping-quotes/:quoteId/confirm
+        participant SH as Shipped
+
+        O->>SWC: Generate quote
+        SWC-->>O: Quote OK
+        O->>SC: Confirm quote
+        SC->>SH: Status
+        SC-->>O: OK
+
+ +
+ + In the ship/custom endpoint response, the quote uuid generated is returned in the latestQuote part: + + ```json + { + "latestQuote": { + "id": "1edd395f-5b57-62ac-9698-521a54b4405f", + "provider": "custom", + ... + } + } + ``` + +
+ + ### Shipping with Ankorstore (asynchronous) + + When calling the `confirm` action for the order's Ankorstore shipping quote, the returned order resource's status + will still be `brand_confirmed`. A job in the background will generate the shipping labels for the order. + It is this background processing that moves the status to `shipping_labels_generated`. + +
+ + #### How will I know when the labels have been generated? + + Right now, the order must be polled periodically. Checking every minute would be suitable to detect the status change + and then pull the label PDF data within the shippingOverview of an order resource. + +
+ + 
+      sequenceDiagram
+        participant O as Order
+        participant SWA as Ship with Ankor : 
 orders/:orderId/shipping-quotes
+        participant SC as Confirm shipping : 
 shipping-quotes/:quoteId/confirm
+        participant BG as Async Processing
+        participant C as Carrier
+        participant SH as Shipped
+
+        O->>SWA: Get shipping quote list
+        SWA-->>O: I accept one quote
+        O->>SC: I confirm the quote
+        SC-->>O: OK status=brand_confirmed
+        SC-->>BG: Dispatch generate labels job
+        Note over SC,BG: Async worker job
+        BG-->>O: Labels generated, status=shipping_labels_generated
+        Note over BG,O: (Async worker)
+        C-->>SH: Parcels scanned, status=shipped
+        Note over C,SH: (External service)
+
+ + At step 6 (shipping labels generated) the download URL's for each packages label will be available within + the shippingOverview of an order resource. These labels are in PDF format and will also be visible in order details page on Ankorstore. + + ### Schedule a Pickup + + If the brand is not taking the parcels to the local drop-off point for the carrier the brand can schedule a pickup + for this order. A pickup can only be scheduled on a working day (monday to friday). + For full information please refer to the API documentation. + +
+ + #### Pickup is not accepted + + For now, Ankorstore does not know in advance which date/time configuration is available, + if the requested pickup is denied please try a different date or time frame. + +
+ + ## ⚠️ Deprecation notice + +
+ + Some of the endpoints and documents from this section are deprecated and will be removed in the future. + You can temporarily still find them [here](#tag/Deprecated). + +
+ - name: Fulfillment + description: | + ℹ️ Here you can find the information and endpoint specification related to fulfillment of the orders. + + ## 💡 About Fulfillment + + _Fulfillment_ is the process of preparing and shipping orders to customers via Ankorstore Fulfillment Centers. + + ### What does "fulfillable" mean? + + The concept of a "fulfillable" is _that which is required to prepare and ship a product (variant)_. + While a Fulfillment Centre deals exclusively with items, which represents a single item that an employee can pick up and prepare for shipping. + A fulfillable is simply a set of one or more items, that together represent a product as ordered + - name: Webhooks + description: | + ℹ️ This section describes the API endpoints which can be used for managing webhook subscriptions. + + ## 💡 Overview + In order to be able to manage Webhook Subscriptions via API you should understand the relationship model + around webhook notifications system. In general, a Webhook Subscription always contains a list of chosen events + and always belongs to an application. More on this later. + + ### Application + Application is a representation of a single private integration. Whenever you create a new set of credentials for + accessing API in your account, under the hood you create an Application entity. Once created, the entity allows you + to attach as many Webhook Subscriptions as needed. It means, there's no way to manage Webhook Subscriptions outside of + Application context and this restriction is also reflected in the current API architecture. + + ### Webhook Subscription + Webhook Subscription is an entity representing "an intent of receiving HTTP requests to the specified URL whenever + one of the chosen Webhook Subscription Events is triggered on the platform". For every new URL you should create a + separate Webhook Subscription. + + ### Webhook Subscription Events + Webhook Subscription Event is a name of the corresponding event fired on certain conditions on the platform. There are + a list of only valid and supported events which can be used in the Webhook Subscription management. You can fetch this + list using a corresponding [endpoint](#tag/Webhooks/operation/get-available-webhook-events) + + ## 💡 How to create a new webhook subscription? + + ### 1. Find ApplicationID + As it was mentioned above, Webhook Subscription always belong to some application. Hence, you should start from + finding out the ID of the target Application in order to link the new Webhook Subscription to it. For this purpose + you should use [List Applications](#tag/Applications/operation/list-applications) endpoint. This endpoint returns + a list of all available Applications in your account, so you could identify the needed one by `name`, `developerEmail` + or `clientId` in the Application resource body: + + `GET https://ankorstore.com/api/v1/applications` + ```json + { + "data": { + "id": "43efbfbd-bfbd-1eef-1e6a-6200efbfbdef", + "type": "application", + "attributes": { + "name": "My Application", + "developerEmail": "dev@acme.com", + "clientId": "k322k7frs87e8w7hri3jkke7ry7", + "clientSecret": null + } + } + } + ``` + **NOTE**: The client secret in the response is always `null` due to security reasons. The actual client secret + can be seen only via UI and only once - during the creation of the application. + + ### 2. Find valid webhook events to subscribe to + Next step should be to find the valid names of the webhook events which you could use in the create webhook request + payload: + + `GET https://ankorstore.com/api/v1/webhook-subscriptions/events` + ```json + { + "data": [ + { + "type": "webhook-subscriptions/events", + "id": "order.brand_created" + }, + { + "type": "webhook-subscriptions/events", + "id": "order.brand_accepted" + } + ] + } + ``` + You can find detailed description of each event in the [dedicated section](#tag/Webhook-Subscription) of the docs. + + ### 3. Create webhook subscription + Now you are all set for creating actual webhook subscription. The prerequisites for this step are: + - The Application ID from step 1 (`43efbfbd-bfbd-1eef-1e6a-6200efbfbdef` in this example) + - The chosen events from step 2 (e.g. `order.brand_created` and `order.brand_accepted`) + With this setup the final request should look like: + + `POST https://ankorstore.com/api/v1/webhook-subscriptions` + ```json + { + "data": { + "type": "webhook-subscriptions", + "attributes": { + "url": "https://my-app.com/webhook-listener", + "events": [ + "order.brand_created", + "order.brand_accepted" + ] + }, + "relationships": { + "application": { + "data": { + "type": "applications", + "id": "43efbfbd-bfbd-1eef-1e6a-6200efbfbdef" + } + } + } + } + } + ``` + After this request is succeeded, you will start receiving notification about chosen events on the chosen URL. + + ## 💡 How to manage existing Webhook Subscriptions? + For most of the operations with an existing Webhook Subscription you need to fetch its ID first. It can be achieved by + using [List Applications](#tag/Applications/operation/list-applications) endpoint and explicit including + the Webhook Subscription resource into the response. + + `GET /api/v1/applications?include=webhookSubscriptions` + ```json + { + "data": { + "id": "`43efbfbd-bfbd-1eef-1e6a-6200efbfbdef", + "type": "applications", + "attributes": {}, + "relationships": { + "webhookSubscriptions": { + "data": [ + { + "type": "webhook-subscriptions", + "id": "a863e15d-3d20-4af2-b92b-d9590a4a9606" + } + ] + } + } + }, + "includes": [ + { + "type": "webhook-subscriptions", + "id": "a863e15d-3d20-4af2-b92b-d9590a4a9606", + "attributes": { + "url": "https://my-app.com/webhook-listener", + "events": [ + "order.brand_created", + "order.brand_accepted" + ], + "signingSecret": "LQxZs6kiSyNr45hjT32OsntYddzH4BvToLIQcgSL" + } + } + ] + } + ``` + + The data in this response gives you an idea about the current Webhook Subscription state and also lets you update + or delete Webhook Subscriptions, whenever needed. For updating or deleting Webhook Subscription you need to use the + Webhook Subscription ID received in the response (`a863e15d-3d20-4af2-b92b-d9590a4a9606` in this particular case). Please + refer to the [Update webhook subscription](#tag/Webhooks/operation/update-application-webhook-subscription) + and [Delete webhook subscription](#tag/Webhooks/operation/delete-application-webhook-subscription) endpoints + for detailed information. + - name: Testing + description: | + ℹ️ This section is dedicated to the testing API during development process. + The listed endpoints are **not available** on production environment. + + ### Creating Test Orders + + When using the public sandbox, a subsection of the API will be available to create test orders. + + This endpoint `/api/testing/orders/create` can be called to create a new test order with a new retailer, + and a couple of new products. + + You can also pass in options to specify the exact retailer or products themselves. + To find out more, you can view the [endpoint specification here](a45de155779ff-create-test-order-sandbox-only). + + ### Finding the Retailer ID + + There is an option to specify the `retailerId` to use the same retailer for every test order, to find this, + login as that retailer you created and open up the developer tools. You will see it logged to the console. + - name: Deprecated + description: | + ℹ️ Here you can find the endpoints which are currently deprecated and will be removed in the future versions of the API. + We strongly encourage you to migrate away from these endpoints in order to prevent any future problems with API. + + ## ❄️ Shipping an Order + + | ⚡ This documentation is deprecated | + |------------------------------------| + + When shipping with either method `ankorstore` or `custom` the brand must provide the parcel data it intends to ship the products in. This parcel information is required when generating a quote with either shipping method: + + - `/v1/orders/{id}/ship/custom` + - `/v1/orders/{id}/ship/ankorstore` + + The brand can generate many quotes between both providers or a single one with different parcel configurations before they decide to **confirm** the quote. An example flow: + + 
+      sequenceDiagram
+
+      participant O as Order
+      participant SWC as Ship Custom
+      participant SWA as Ship Ankor
+      participant SC as Ship Confirm
+
+      O->>SWC: Generate quote
+      SWC-->>O: Unhappy with refund
+      O->>SWA: Generate quote
+      SWA-->>O: Cannot generate quote for retailers ship to address
+      Note over SWA,O: Sometimes AK shipping providers (UPS) cannot ship to certain addresses etc.
+      SWA-->>O: Unhappy with shipping cost fee
+      Note over SWA,O: A fee can be created as a contribution of the brand depending on the shipping costs
+      O->>SWC: Generate new custom quote
+      Note over O,SWC: Quote needs to be regenerated.
+      Note over O,SWC: Confirm endpoint uses last generated quote.
+      SWC->>SC: Brand ships with custom
+
+ + ### Shipping Methods + + Within the `shippingOverview` object, there is a field that holds the supported shipping methods for an order: + + ```json + { + "status": "brand_confirmed", + ... + "shippingOverview": { + "availableShippingMethods": ["custom", "ankorstore"] + } + } + ``` + + Please check this before attempting to ship with ankorstore as it may not be available. + +
+ + #### Parcels + + On either shipping method, if the brand has previously generated a quote and is now generating a new one the full list of parcels must be provided. The quote endpoint **cannot** be called with an empty parcel list to re-use the old parcel data. + +
+ +
+ + #### Confirming a quote + + When confirming a quote only the **last generated quote** is used - this is the one in the order resource `latestQuote`. The `/v1/orders/{id}/ship/confirm` endpoint does not currently accept a quote ID. + +
+ + Apart from `shippingMethod` that is at the order resource level, all information regarding shipping and tracking is stored within the `shippingOverview` object. This includes the `latestQuote` generated and the `shippingCostsOverview`. + + ### Shipping Costs Overview + +
+ + We advise you to pay attention on the shippingCostsOverview object, especially when type=fee as the amount referenced here will be subtracted from the brandTotalAmount. + +
+ + In the `latestQuote` object, an object called `shippingCostsOverview` might appear depending on the shipping method selected. + This object includes the cost of the shipping and the type of the cost : + + Fee payload example : + + ```json + { + "shippingCostsOverview": { + "amount": 5160, + "currency": "EUR", + "type": "fee" + } + } + ``` + + Refund payload example : + + ```json + { + "shippingCostsOverview": { + "amount": 1060, + "currency": "EUR", + "type": "refund" + } + } + ``` + + If the type is **fee**, it means that this amount will be subtracted from brand net amount as a contribution to shipping costs. If the type is **refund**, the amount will be refunded to the brand. + +
+ + #### Want more information about shipping contribution? + + To find out more about Ankorstore's contribution to your shipping costs, please [visit our FAQs.](https://knowledgecommunity.force.com/faq/s/article/shippingpolicy?language=en_US) + +
+ + ### Shipping with the brands own carrier + + The quote action will return an amount that will be refunded back to the brand based on the shipping grid refund matrix. + + The confirm action is synchronous, meaning when the action is called the order resource will have its status changed to `shipped` upon returning a response. It is up to brand to provide tracking details for the retailer when calling this action. + + 
+      sequenceDiagram
+
+        participant O as Order
+        participant SWC as Ship Custom
+        participant SC as Ship Confirm
+        participant SH as Shipped
+
+        O->>SWC: Generate quote
+        SWC-->>O: Quote OK
+        O->>SC: Confirm quote
+        SC->>SH: Status
+        SC-->>O: OK
+
+ + ### Shipping with Ankorstore (asynchronous) + + When calling the confirm action for the order's Ankorstore shipping quote, the returned order resource's status will still be `brand_confirmed`. A job in the background will generate the shipping labels for the order. It is this background processing that moves the status to `shipping_labels_generated`. + +
+ + #### How will I know when the labels have been generated? + + Right now, the order must be polled periodically. Checking every minute would be suitable to detect the status change and then pull the label PDF data within the shippingOverview of an order resource. + +
+ + 
+      sequenceDiagram
+
+        participant O as Order
+        participant SWA as Ship Ankor
+        participant SC as Ship Confirm
+        participant BG as Async Processing
+        participant C as Carrier
+        participant SH as Shipped
+
+        O->>SWA: Generate quote
+        SWA-->>O: Quote OK
+        O->>SC: Confirm quote
+        SC-->>O: OK status=brand_confirmed
+        SC-->>BG: Dispatch generate labels job
+        Note over SC,BG: Async worker job
+        BG-->>O: Labels generated, status=shipping_labels_generated
+        Note over BG,O: (Async worker)
+        C-->>SH: Parcels scanned, status=shipped
+        Note over C,SH: (External service)
+
+ + At step 6 (shipping labels generated) the download URL's for each packages label will be available within the shippingOverview of an order resource. These labels are in PDF format and will also be visible in order details page on Ankorstore. + + ### Schedule a Pickup + + If the brand is not taking the parcels to the local drop-off point for the carrier the brand can schedule a pickup for this order. A pickup can only be scheduled on a working day (monday to friday). For full information please refer to the API documentation. + +
+ + #### Pickup is not accepted + + For now, Ankorstore does not know in advance which date/time configuration is available, if the requested pickup is denied please try a different date or time frame. + +
+externalDocs: + description: Ankorstore API Specification + url: https://api-spec.ankorstore.com +paths: + /api/v1/currencies/rates/latest: + get: + summary: List of latest currency rates + operationId: get-currencies-rates-latest + description: Returns a list of the latest currency rates + tags: + - General + parameters: + - name: Accept + in: header + description: application/vnd.api+json + schema: &ref_3 + type: string + default: application/vnd.api+json + responses: + '200': + description: Set of currency exchange rates + content: &ref_160 + application/vnd.api+json: + schema: + type: object + properties: + data: + type: array + items: + properties: &ref_87 + type: + type: string + description: '[resource object type](https://jsonapi.org/format/#document-resource-object-identification)' + id: + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + attributes: + type: object + properties: &ref_86 + fromCurrency: + type: string + pattern: ^[A-Z]{3}$ + toCurrency: + type: string + pattern: ^[A-Z]{3}$ + date: + type: string + format: date + rate: + type: number + required: &ref_88 + - type + - id + - attributes + jsonapi: + description: An object describing the server's implementation + type: object + properties: &ref_0 + version: + type: string + meta: + description: Non-standard meta-information that can not be represented as an attribute or relationship. + type: object + additionalProperties: true + additionalProperties: false + required: + - data + - jsonapi + '401': + description: Unauthorized + content: &ref_4 + application/vnd.api+json: + schema: + type: object + additionalProperties: false + properties: &ref_1 + errors: + type: array + uniqueItems: true + items: + type: object + properties: &ref_85 + code: + description: An application-specific error code, expressed as a string value. + type: string + detail: + description: A human-readable explanation specific to this occurrence of the problem. + type: string + status: + description: The HTTP status code applicable to this problem, expressed as a string value. + type: string + title: + description: The HTTP status code description applicable to this problem + type: string + source: + type: object + description: Optional object pointing towards the problematic field + properties: + pointer: + type: string + description: The field key + additionalProperties: false + jsonapi: + description: An object describing the server's implementation + type: object + properties: *ref_0 + additionalProperties: false + required: &ref_2 + - errors + example: + jsonapi: + version: '1.0' + errors: + - detail: Unauthorized + status: '401' + '406': + description: Not Acceptable + content: &ref_5 + application/vnd.api+json: + schema: + type: object + additionalProperties: false + properties: *ref_1 + required: *ref_2 + example: + jsonapi: + version: '1.0' + errors: + - detail: Not Acceptable + status: '406' + '415': + description: Unsupported Media Type + content: &ref_6 + application/vnd.api+json: + schema: + type: object + additionalProperties: false + properties: *ref_1 + required: *ref_2 + example: + jsonapi: + version: '1.0' + errors: + - detail: Unsupported Media Type + status: '415' + '500': + description: '[Server Error](https://jsonapi.org/format/#errors)' + content: &ref_7 + application/vnd.api+json: + schema: + type: object + additionalProperties: false + properties: *ref_1 + required: *ref_2 + example: + jsonapi: + version: '1.0' + errors: + - detail: Server Error + status: '500' + /api/v1/me/config: + get: + summary: Configuration for the current user + operationId: get-me-config + description: Returns configuration for the current user + tags: + - User + parameters: + - name: Accept + in: header + description: application/vnd.api+json + schema: *ref_3 + responses: + '200': + description: User config + content: &ref_8 + application/vnd.api+json: + schema: + type: object + properties: + data: + properties: &ref_90 + type: + type: string + description: '[resource object type](https://jsonapi.org/format/#document-resource-object-identification)' + id: + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + attributes: + type: object + properties: &ref_89 + currency: + type: string + country: + type: string + browserId: + type: string + required: &ref_91 + - type + - id + - attributes + jsonapi: + description: An object describing the server's implementation + type: object + properties: *ref_0 + additionalProperties: false + required: + - data + - jsonapi + '401': + description: Unauthorized + content: *ref_4 + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 + '500': + description: '[Server Error](https://jsonapi.org/format/#errors)' + content: *ref_7 + /api/v1/users/{id}/config: + get: + summary: Configuration for the specified user + operationId: get-user-config + description: Returns configuration of the specified user + tags: + - User + parameters: + - schema: + type: string + format: uuid + name: id + in: path + required: true + description: User ID + - name: Accept + in: header + description: application/vnd.api+json + schema: *ref_3 + responses: + '200': + description: User config + content: *ref_8 + '401': + description: Unauthorized + content: *ref_4 + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 + '500': + description: '[Server Error](https://jsonapi.org/format/#errors)' + content: *ref_7 + /api/v1/products: + get: + summary: List Products + description: Returns all products + operationId: list-products + tags: + - Catalog + parameters: + - name: Accept + in: header + description: application/vnd.api+json + schema: *ref_3 + - name: page[limit] + in: query + description: limit the amount of results returned + required: false + schema: &ref_32 + type: integer + format: int64 + - name: page[before] + in: query + description: show items before the provided ID (uuid format) + required: false + schema: &ref_33 + type: string + - name: page[after] + in: query + description: show items after the provided ID (uuid format) + required: false + schema: &ref_34 + type: string + responses: + '200': + description: '[OK](https://jsonapi.org/format/#fetching-resources-responses-200)' + content: + application/vnd.api+json: + schema: + type: object + title: Product Collection + required: &ref_92 + - data + properties: &ref_93 + meta: + type: object + description: Meta with Pagination Details + required: &ref_17 + - page + additionalProperties: true + properties: &ref_18 + page: + description: Cursor pagination details + type: object + properties: + from: + type: + - string + - 'null' + to: + type: + - string + - 'null' + hasMore: + type: boolean + perPage: + type: integer + required: + - from + - to + - hasMore + - perPage + jsonapi: + description: An object describing the server's implementation + type: object + properties: *ref_0 + additionalProperties: false + links: + description: Pagination navigation links. If a link does not exist then you cannot paginate any further in that direction. + type: object + properties: &ref_19 + first: + type: string + format: url + next: + type: string + format: url + prev: + type: string + format: url + data: + description: List of Product resource objects + type: array + uniqueItems: true + items: + title: Product Resource + description: The resource object for Product + type: object + additionalProperties: false + properties: &ref_10 + type: + type: string + description: '[resource object type](https://jsonapi.org/format/#document-resource-object-identification)' + id: + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + attributes: + type: object + properties: + name: + type: string + description: The name of the product + description: + type: string + description: The description of the product + language: + type: string + description: The language of the title and description + dimensions: + type: string + description: The human readable dimensions of the product + netWeight: + type: string + description: The weight of the product itself + capacity: + type: string + description: eg. Capacity in weight eg 100g + position: + type: number + description: The position of the product in the brands catalog, lower the higher it is + unitMultiplier: + type: integer + description: How many products are shipped together, ie a case of 6 wine bottles. Presented options then would be 6, 12, 18 etc. + vatRate: + type: number + format: float + description: The VAT rate of the product + discountRate: + description: The percentage discount if a brand is offering one (0 - 1) + type: number + format: float + productTypeId: + description: Product Type ID + type: number + format: integer + active: + type: boolean + description: Whether the product is active or not + outOfStock: + type: boolean + description: Whether the product is out of stock or not + archived: + type: boolean + description: Whether the product is archived or not + retailPrice: + description: The suggested retail price of the product + type: integer + wholesalePrice: + description: The wholesale price after the discount rate is applied + type: integer + originalWholesalePrice: + description: The original wholesale price set by the brand + type: integer + createdAt: + type: string + format: datetime + description: The timestamp when the product was created + indexedAt: + type: + - 'null' + - string + format: datetime + description: The timestamp when the product was indexed + updatedAt: + type: string + format: datetime + description: The timestamp when the product was updated + images: + type: array + items: + image: + type: object + properties: + order: + type: integer + url: + type: string + tags: + type: array + items: + tag: + type: string + relationships: + type: object + properties: + productOption: + description: 'Reference: Product Option Resource' + type: object + properties: + data: + description: An array of objects each containing `type` and `id` members for to-many relationships. + type: array + items: &ref_9 + description: Resource identification present in Resource Objects and Resource Identifier Objects. + type: object + required: &ref_12 + - id + - type + properties: &ref_13 + id: + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + type: + type: string + description: '[resource object type](https://jsonapi.org/format/#document-resource-object-identification)' + meta: + description: Non-standard meta-information that can not be represented as an attribute or relationship. + type: object + additionalProperties: true + additionalProperties: false + uniqueItems: true + productVariant: + description: 'Reference: Product Variant Resource' + type: object + properties: + data: + description: An array of objects each containing `type` and `id` members for to-many relationships. + type: array + items: *ref_9 + uniqueItems: true + required: &ref_11 + - type + - id + additionalProperties: false + examples: + example: + value: + meta: + page: + from: 123e4567-e89b-12d3-a456-426614174000 + hasMore: true + perPage: 2 + to: 1ecb023e-7ec0-6d5c-a477-0242ac170008 + jsonapi: + version: '1.0' + links: + first: https://www.ankorstore.com/api/v1/orders?include=&page%5Blimit%5D=2 + next: https://www.ankorstore.com/api/v1/orders?include=&page%5Bafter%5D=797910&page%5Blimit%5D=2 + prev: https://www.ankorstore.com/api/v1/orders?include=&page%5Bbefore%5D=904234&page%5Blimit%5D=2 + data: + - type: product + id: 0c5e6540-0da9-1ecb-bf59-0242ac170007 + attributes: + name: Example Product + description: Example description of product + language: fr + dimensions: 5,5x5,5x6 + netWeight: 100G + capacity: 100g + position: 34 + unitMultiplier: 12 + vatRate: 5.5 + discountRate: 0 + active: true + outOfStock: false + archived: false + retailPrice: 750 + wholesalePrice: 426 + originalWholesalePrice: 426 + createdAt: '2020-08-27T14:26:38.000000Z' + indexedAt: '2022-02-10T03:26:11.000000Z' + updatedAt: '2022-02-09T14:49:09.000000Z' + - type: product + id: c8466a3c-4fb8-4474-a86f-20f10d14314f + attributes: + name: Example Product 2 + description: Example description of product 2 + language: fr + dimensions: 10,5x10,5x12 + netWeight: 250G + capacity: 250g + position: 20 + unitMultiplier: 12 + vatRate: 5.5 + discountRate: 0 + active: true + outOfStock: false + archived: false + retailPrice: 900 + wholesalePrice: 700 + originalWholesalePrice: 700 + createdAt: '2020-09-27T14:26:38.000000Z' + indexedAt: '2022-02-10T03:26:11.000000Z' + updatedAt: '2022-02-09T14:49:09.000000Z' + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 + /api/v1/products/{product}: + get: + summary: Get Product + description: Retrieve a specific product + operationId: get-product + tags: + - Catalog + parameters: + - name: Accept + in: header + description: application/vnd.api+json + schema: *ref_3 + - name: product + in: path + required: true + schema: &ref_156 + default: 079ba9ad-dcdb-4dda-ba0a-1174dad313c5 + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + - name: include + in: query + description: '[Include Product Variants](https://ankorstore.github.io/api-docs/#tag/Product/Working-with-Products/Including-Product-Variants)' + allowEmptyValue: true + required: false + schema: &ref_157 + type: string + responses: + '200': + description: '[OK](https://jsonapi.org/format/#fetching-resources-responses-200)' + content: + application/vnd.api+json: + schema: + type: object + additionalProperties: false + title: Product Get + properties: &ref_94 + jsonapi: + description: An object describing the server's implementation + type: object + properties: *ref_0 + additionalProperties: false + data: + title: Product Resource + description: The resource object for Product + type: object + additionalProperties: false + properties: *ref_10 + required: *ref_11 + included: + description: To reduce the number of HTTP requests, servers **MAY** allow responses that include related resources along with the requested primary resources. Such responses are called `compound documents`. + type: + - array + - 'null' + uniqueItems: true + items: + anyOf: + - title: Product Variant Resource + description: Variant details for a given product. Unique products will have one single variant. + type: object + additionalProperties: false + examples: &ref_14 + - type: productVariant + id: 2171bdc1-fa01-44fa-9342-d99bd1c2befa + attributes: + name: Test Product Variant + sku: Product-Variant-001 + ian: '1924859325863' + createdAt: '2020-08-27T14:29:15.000000Z' + updatedAt: '2021-10-04T12:03:31.000000Z' + archivedAt: null + retailPrice: 800 + wholesalePrice: 500 + originalWholesalePrice: 500 + availableQuantity: 125 + reservedQuantity: 25 + stockQuantity: 150 + isAlwaysInStock: false + fulfillableId: 8f066352-67cb-1efa-bddb-9e3047198b2e + availableAt: '2028-01-01T00:00:00.000000Z' + images: + - order: 1 + url: https://example.com/image1.jpg + - order: 2 + url: https://example.com/image2.jpg + relationships: + product: + data: + type: product + id: c8466a3c-4fb8-4474-a86f-20f10d14314f + properties: &ref_15 + type: + type: string + description: '[resource object type](https://jsonapi.org/format/#document-resource-object-identification)' + id: + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + attributes: + type: object + properties: + name: + type: string + description: The name of the product variant + sku: + type: string + description: The SKU of the product variant + ian: + type: + - 'null' + - string + description: The IAN (EAN) of the product variant, can be null + createdAt: + type: string + format: datetime + description: Timestamp of when this product variant was created + updatedAt: + type: string + format: datetime + description: Timestamp of when this product variant was updated + archivedAt: + type: + - 'null' + - string + description: Timestamp of when this product variant was archived + retailPrice: + description: The suggested retail price of the product + type: integer + wholesalePrice: + description: The wholesale price after the discount rate is applied + type: integer + originalWholesalePrice: + description: The original wholesale price set by the brand + type: integer + availableQuantity: + type: + - 'null' + - integer + description: Number of items available + reservedQuantity: + type: integer + description: Number of items in stock that are reserved + stockQuantity: + type: + - 'null' + - integer + description: Total number of items in stock + isAlwaysInStock: + type: boolean + description: True if the product is always in stock, false otherwise + fulfillableId: + type: + - 'null' + - string + format: uuid + description: Resource ID used for interacting with the fulfillment service + availableAt: + type: string + nullable: true + format: date + description: Shipping date(in future) of a preorder product e.g. 2028-12-01 + images: + type: array + items: + image: + type: object + properties: + order: + type: integer + url: + type: string + relationships: + type: object + properties: + product: + description: 'Reference: Product Resource' + type: object + properties: + data: + description: Resource identification present in Resource Objects and Resource Identifier Objects. + type: object + required: *ref_12 + properties: *ref_13 + additionalProperties: false + required: &ref_16 + - type + - id + - title: Product Option Resource + description: A unique option for a product + type: object + additionalProperties: false + examples: &ref_45 + - type: productOption + id: 7ec06d5c-023e-1ecb-a477-0242ac170007 + attributes: + name: Test Product Option + sku: '051100' + ian: '3770005999506' + outOfStock: false + createdAt: '2020-08-27T14:29:15.000000Z' + updatedAt: '2021-10-04T12:03:31.000000Z' + archivedAt: null + relationships: + product: + data: + type: product + id: 7f4665f6-023e-1ecb-a4b2-0242ac170007 + properties: &ref_46 + type: + type: string + description: '[resource object type](https://jsonapi.org/format/#document-resource-object-identification)' + id: + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + attributes: + type: object + properties: + name: + type: string + description: The name of the option + sku: + type: string + description: The SKU of the option + ian: + type: + - 'null' + - string + description: The IAN (EAN) of the option, can be null + outOfStock: + type: boolean + description: Whether the product is in stock or not + createdAt: + type: string + format: datetime + description: Timestamp of when this option was created + updatedAt: + type: string + format: datetime + description: Timestamp of when this option was updated + archivedAt: + type: + - 'null' + - string + description: Timestamp of when this option was archived + relationships: + type: object + properties: + product: + description: 'Reference: Product Resource' + type: object + properties: + data: + description: Resource identification present in Resource Objects and Resource Identifier Objects. + type: object + required: *ref_12 + properties: *ref_13 + additionalProperties: false + required: &ref_47 + - type + - id + examples: &ref_95 + - jsonapi: + $ref: ../../v1.yaml#/components/schemas/jsonapi + data: + type: product + id: 0c5e6540-0da9-1ecb-bf59-0242ac170007 + attributes: + name: Example Product + description: Example description of product + language: fr + dimensions: 5,5x5,5x6 + netWeight: 100G + capacity: 100g + position: 34 + unitMultiplier: 12 + vatRate: 5.5 + discountRate: 0 + active: true + outOfStock: false + archived: false + retailPrice: 750 + wholesalePrice: 426 + originalWholesalePrice: 426 + createdAt: '2020-08-27T14:26:38.000000Z' + indexedAt: '2022-02-10T03:26:11.000000Z' + updatedAt: '2022-02-09T14:49:09.000000Z' + included: + - type: productVariant + id: 3571bdc1-fa01-44fa-9342-d99bd1c2befa + attributes: + name: Test Product Variant + sku: Product-Variant-001 + ian: '1924859325863' + createdAt: '2020-08-27T14:29:15.000000Z' + updatedAt: '2021-10-04T12:03:31.000000Z' + archivedAt: null + retailPrice: 800 + wholesalePrice: 500 + originalWholesalePrice: 500 + availableQuantity: 125 + reservedQuantity: 25 + stockQuantity: 150 + isAlwaysInStock: false + fulfillableId: 8f066352-67cb-1efa-bddb-9e3047198b2e + availableAt: '2028-01-01T00:00:00.000000Z' + images: + - order: 1 + url: https://example.com/image1.jpg + - order: 2 + url: https://example.com/image2.jpg + required: &ref_96 + - data + examples: + example: + value: + jsonapi: + version: '1.0' + data: + type: product + id: 0c5e6540-0da9-1ecb-bf59-0242ac170007 + attributes: + name: Example Product + description: Example description of product + language: fr + dimensions: 5,5x5,5x6 + netWeight: 100G + capacity: 100g + position: 34 + unitMultiplier: 12 + vatRate: 5.5 + discountRate: 0 + productTypeId: 1 + active: true + outOfStock: false + archived: false + retailPrice: 750 + wholesalePrice: 426 + originalWholesalePrice: 426 + createdAt: '2020-08-27T14:26:38.000000Z' + indexedAt: '2022-02-10T03:26:11.000000Z' + updatedAt: '2022-02-09T14:49:09.000000Z' + images: + - order: 1 + url: https://example.com/image1.jpg + - order: 2 + url: https://example.com/image2.jpg + tags: + - tags_organic + - tags_handmade + - tags_eco_friendly + included: + - type: productVariant + id: 2171bdc1-fa01-44fa-9342-d99bd1c2befa + attributes: + name: Test Product Variant + sku: Product-Variant-001 + ian: '1924859325863' + createdAt: '2020-08-27T14:29:15.000000Z' + updatedAt: '2021-10-04T12:03:31.000000Z' + archivedAt: null + retailPrice: 800 + wholesalePrice: 500 + originalWholesalePrice: 500 + availableQuantity: 125 + reservedQuantity: 25 + stockQuantity: 150 + isAlwaysInStock: false + relationships: + product: + data: + type: product + id: c8466a3c-4fb8-4474-a86f-20f10d14314f + '401': + description: Unauthorized + content: *ref_4 + '404': + description: '[Not found](https://jsonapi.org/format/#fetching-resources-responses-404)' + content: &ref_21 + application/vnd.api+json: + schema: + type: object + additionalProperties: false + properties: *ref_1 + required: *ref_2 + example: + jsonapi: + version: '1.0' + errors: + - detail: Not found + status: '404' + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 + /api/v1/product-variants: + get: + summary: List Product Variants + description: Returns all product variants with their stock + operationId: list-product-variants-with-stock + tags: + - Catalog + parameters: + - schema: + type: string + in: header + name: Accept + description: application/vnd.api+json + - name: filter[sku] + in: query + description: Filter by SKU(s) + required: false + schema: + type: array + items: + type: string + style: form + explode: true + example: + - MY-SKU12,MY-SKU34 + responses: + '200': + description: '[OK](https://jsonapi.org/format/#fetching-resources-responses-200)' + content: + application/vnd.api+json: + schema: + type: object + required: &ref_97 + - data + properties: &ref_98 + data: + description: List of Product Variant resource objects + type: array + uniqueItems: true + items: + title: Product Variant Resource + description: Variant details for a given product. Unique products will have one single variant. + type: object + additionalProperties: false + examples: *ref_14 + properties: *ref_15 + required: *ref_16 + meta: + type: object + description: Meta with Pagination Details + required: *ref_17 + additionalProperties: true + properties: *ref_18 + links: + description: Pagination navigation links. If a link does not exist then you cannot paginate any further in that direction. + type: object + properties: *ref_19 + jsonapi: + description: An object describing the server's implementation + type: object + properties: *ref_0 + additionalProperties: false + additionalProperties: false + title: Product Variant Collection + examples: + example: + value: + meta: + page: + from: 3571bdc1-fa01-44fa-9342-d99bd1c2befa + hasMore: true + perPage: 2 + to: 4271bdc1-fa01-44fa-9342-d99bd1c2befa + jsonapi: + version: '1.0' + links: + first: https://www.ankorstore.com/api/v1/product-variants?include=&page%5Blimit%5D=2 + next: https://www.ankorstore.com/api/v1/product-variants?include=&page%5Bafter%5D=4271bdc1-fa01-44fa-9342-d99bd1c2befa&page%5Blimit%5D=2 + prev: https://www.ankorstore.com/api/v1/product-variants?include=&page%5Bbefore%5D=3571bdc1-fa01-44fa-9342-d99bd1c2befa&page%5Blimit%5D=2 + data: + - type: productVariant + id: 3571bdc1-fa01-44fa-9342-d99bd1c2befa + attributes: + name: Test Product Variant + sku: Product-Variant-001 + ian: '1924859325863' + createdAt: '2020-08-27T14:29:15.000000Z' + updatedAt: '2021-10-04T12:03:31.000000Z' + archivedAt: null + retailPrice: 800 + wholesalePrice: 500 + originalWholesalePrice: 500 + availableQuantity: 125 + reservedQuantity: 25 + stockQuantity: 150 + isAlwaysInStock: false + relationships: + product: + data: + type: product + id: 4271bdc1-fa11-54fa-9242-d99bd1c2befb + - type: productVariant + id: 4271bdc1-fa01-44fa-9342-d99bd1c2befa + attributes: + name: Another test Product Variant + sku: Product-Variant-002 + ian: '1924859325867' + createdAt: '2020-08-27T14:29:15.000000Z' + updatedAt: '2021-10-04T12:03:31.000000Z' + archivedAt: null + retailPrice: 800 + wholesalePrice: 500 + originalWholesalePrice: 500 + availableQuantity: 125 + reservedQuantity: 25 + stockQuantity: 150 + isAlwaysInStock: false + relationships: + product: + data: + type: product + id: 2291bdc1-bc01-44fa-9342-d95bd1c2befa + '401': + description: Unauthorized + content: *ref_4 + '403': + description: '[Forbidden](https://jsonapi.org/format/#crud-creating-responses-403)' + content: &ref_20 + application/vnd.api+json: + schema: + type: object + additionalProperties: false + properties: *ref_1 + required: *ref_2 + example: + jsonapi: + version: '1.0' + errors: + - detail: Forbidden + status: '403' + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 + /api/v1/product-variants/{productVariant}: + get: + summary: Get Product Variant + description: Get product variant with stock + operationId: get-product-variant-with-stock + tags: + - Catalog + parameters: + - name: Accept + in: header + description: application/vnd.api+json + schema: *ref_3 + - name: productVariant + in: path + required: true + schema: &ref_22 + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + responses: + '200': + description: '[OK](https://jsonapi.org/format/#fetching-resources-responses-200)' + content: &ref_23 + application/vnd.api+json: + schema: + type: object + properties: + data: + title: Product Variant Resource + description: Variant details for a given product. Unique products will have one single variant. + type: object + additionalProperties: false + examples: *ref_14 + properties: *ref_15 + required: *ref_16 + jsonapi: + description: An object describing the server's implementation + type: object + properties: *ref_0 + additionalProperties: false + required: + - data + '401': + description: Unauthorized + content: *ref_4 + '403': + description: '[Forbidden](https://jsonapi.org/format/#crud-creating-responses-403)' + content: *ref_20 + '404': + description: '[Not found](https://jsonapi.org/format/#fetching-resources-responses-404)' + content: *ref_21 + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 + /api/v1/product-variants/{productVariant}/stock: + patch: + summary: Update Product Variant Stock + description: Update product variant stock + operationId: update-product-variant-stock + tags: + - Catalog + parameters: + - name: Accept + in: header + description: application/vnd.api+json + schema: *ref_3 + - name: productVariant + in: path + required: true + schema: *ref_22 + responses: + '200': + description: '[OK](https://jsonapi.org/format/#fetching-resources-responses-200)' + content: *ref_23 + '401': + description: Unauthorized + content: *ref_4 + '403': + description: '[Forbidden](https://jsonapi.org/format/#crud-creating-responses-403)' + content: *ref_20 + '404': + description: '[Not found](https://jsonapi.org/format/#fetching-resources-responses-404)' + content: *ref_21 + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 + requestBody: + content: + application/vnd.api+json: + schema: + type: object + additionalProperties: false + properties: + data: + anyOf: + - title: ProductVariantStockUpdateSetStockQuantity + type: object + description: A request schema to update product variant stock value by setting explicit stock quantity. + properties: &ref_82 + id: + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + type: + type: string + description: '[resource object type](https://jsonapi.org/format/#document-resource-object-identification)' + attributes: + type: object + required: + - stockQuantity + properties: + stockQuantity: + type: number + minimum: 0 + example: 100 + required: &ref_83 + - id + - type + - attributes + examples: &ref_84 + - type: productVariant + id: 1e7b432b-50d4-4495-b032-6cbbc5f6f023 + attributes: + stockQuantity: 100 + - title: ProductVariantStockUpdateSetIsAlwaysInStockRequest + type: object + examples: &ref_79 + - type: productVariants + id: ec5d2b52-4911-4eff-9846-71787f9f02df + attributes: + isAlwaysInStock: true + properties: &ref_80 + id: + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + type: + type: string + description: '[resource object type](https://jsonapi.org/format/#document-resource-object-identification)' + attributes: + type: object + required: + - isAlwaysInStock + properties: + isAlwaysInStock: + type: boolean + description: Whether the current product variant is always in stock + required: &ref_81 + - id + - type + - attributes + description: A request schema to update product variant stock value by setting option "always in stock" to true. It will also reset any possibly previously existed explicit stock quantities. + required: + - data + examples: + example: + value: + data: + type: product-variants + id: 2171bdc1-fa01-44fa-9342-d99bd1c2befa + attributes: + isAlwaysInStock: false + stockQuantity: 20 + /api/v1/catalog/integrations/operations: + post: + summary: Create a new operation + description: | + Create new Operation to process over related Catalog Integration + > ID of the operation will be returned on the response payload. + This ID should be used to add products data through `POST /catalog/integrations/operations/{ID}` + operationId: post-catalog-integration-operations + tags: + - Catalog Integrations + parameters: + - name: Accept + in: header + description: application/vnd.api+json + schema: *ref_3 + requestBody: + content: &ref_183 + application/vnd.api+json: + schema: + type: object + properties: + data: + type: object + properties: + type: + type: string + description: The type of resource to create + enum: + - catalog-integration-operation + attributes: + type: object + description: The operation attributes + required: + - source + - operationType + - callbackUrl + optional: + - updateFields + properties: + source: + title: OperationSource + description: Source of the operation + type: string + enum: &ref_24 + - shopify + - woocommerce + - prestashop + - other + callbackUrl: + type: string + description: | + The url of the endpoint that will be called when an operation completes. When an operation reaches a completed state such as **Success**, **Failed**, or **Partially Failed** the API platform will trigger a request to your endpoint. + operationType: + title: OperationType + description: Operation type + type: string + enum: + - import + - update + - delete + updateFields: + type: array + description: | + Optional list of fields that will be taken into account when updating the products provided. This list will be + only taken into account for operations of type `update`. + - For sources `shopify`, `woocommerce` and `prestashop`: If list is not provided or empty, all `stock` + and `prices` related fields will be updated + - For source `other`: If list is not provided or empty, all fields will be updated + + Group fields: + - If `stock` is provided, both `stock_quantity` and `is_always_in_stock` properties will be updated + - If `prices` is provided, both `wholesale_price` and `retail_price` will be updated + items: + type: string + enum: + - stock + - prices + - description + - dimensions + - images + - name + - prices + - product_type_id + - retail_price + - stock + - tags + - unit_multiplier + - vat_rate + - wholesale_price + examples: + import: + value: &ref_174 + data: + type: catalog-integration-operation + attributes: + source: shopify + callbackUrl: https://callback.url/called/after/processing + operationType: import + update: + value: &ref_175 + data: + type: catalog-integration-operation + attributes: + source: shopify + callbackUrl: https://callback.url/called/after/processing + operationType: update + updateFields: + - stock + responses: + '201': + description: The operation that was successfully created + content: &ref_28 + application/vnd.api+json: + schema: + type: object + properties: + data: + title: Operation + description: An operation resource + type: object + required: &ref_25 + - id + - type + properties: &ref_26 + id: + type: string + format: uuid + description: A globally-unique identifier for the operation + readOnly: true + type: + type: string + description: Resource type. + enum: + - catalog-integration-operation + readOnly: true + attributes: + type: object + description: The operation attributes. + properties: + source: + title: OperationSource + description: Source of the operation + type: string + enum: *ref_24 + status: + title: OperationStatus + type: string + enum: &ref_99 + - created + - started + - skipped + - succeeded + - partially_failed + - failed + operationType: + title: OperationType + description: Operation type + type: string + enum: &ref_100 + - import + - update + - delete + updateFields: + title: updateFields + description: List of fields or group of fields that will be updated on provided products + type: array + items: &ref_101 + type: string + enum: + - stock + - prices + createdAt: + type: string + format: date-time + description: Date and time when operation was created + startedAt: + type: + - 'null' + - string + format: date-time + description: Date and time when operation processing started + completedAt: + type: + - 'null' + - string + format: date-time + description: Date and time when operation was completed + callbackUrl: + type: + - 'null' + - string + format: uri + description: a URL where the user will be notified after the operation is complete + totalProductsCount: + type: integer + description: Total number of products in the batch + processedProductsCount: + type: integer + description: Number of products successfully processed + failedProductsCount: + type: integer + description: Number of products which processing failed + examples: + Operation Created: + value: &ref_176 + jsonapi: + version: '1.0' + links: + self: https://www.ankorstore.com/api/v1/catalog/integrations/operations/90567710-de47-49e4-8536-aab80c1a469c + data: + id: 90567710-de47-49e4-8536-aab80c1a469c + type: catalog-integration-operation + attributes: + source: shopify + status: created + operationType: import + createdAt: '2024-01-01T14:15:22Z' + startedAt: null + completedAt: null + callbackUrl: https://callback.url/called/after/processing + totalProductsCount: 132 + processedProductsCount: 0 + failedProductsCount: 0 + relationships: + results: + links: + related: https://www.ankorstore.com/api/v1/catalog/integrations/operations/90567710-de47-49e4-8536-aab80c1a469c/results + self: https://www.ankorstore.com/api/v1/catalog/integrations/operations/90567710-de47-49e4-8536-aab80c1a469c/relationships/results + links: + self: https://www.ankorstore.com/api/v1/catalog/integrations/operations/90567710-de47-49e4-8536-aab80c1a469c + Operation Started: + value: &ref_177 + jsonapi: + version: '1.0' + links: + self: https://www.ankorstore.com/api/v1/catalog/integrations/operations/90567710-de47-49e4-8536-aab80c1a469c + data: + id: 90567710-de47-49e4-8536-aab80c1a469c + type: catalog-integration-operation + attributes: + source: shopify + status: started + operationType: import + createdAt: '2024-01-01T14:15:22Z' + startedAt: '2024-01-01T15:27:22Z' + completedAt: null + callbackUrl: https://callback.url/called/after/processing + totalProductsCount: 132 + processedProductsCount: 0 + failedProductsCount: 0 + relationships: + results: + links: + related: https://www.ankorstore.com/api/v1/catalog/integrations/operations/90567710-de47-49e4-8536-aab80c1a469c/results + self: https://www.ankorstore.com/api/v1/catalog/integrations/operations/90567710-de47-49e4-8536-aab80c1a469c/relationships/results + links: + self: https://www.ankorstore.com/api/v1/catalog/integrations/operations/90567710-de47-49e4-8536-aab80c1a469c + Operation Succeeded: + value: &ref_178 + jsonapi: + version: '1.0' + links: + self: https://www.ankorstore.com/api/v1/catalog/integrations/operations/90567710-de47-49e4-8536-aab80c1a469c + data: + id: 90567710-de47-49e4-8536-aab80c1a469c + type: catalog-integration-operation + attributes: + source: shopify + status: succeeded + operationType: import + createdAt: '2024-01-01T14:15:22Z' + startedAt: '2024-01-01T15:27:45Z' + completedAt: '2024-01-01T16:10:03Z' + callbackUrl: https://callback.url/called/after/processing + totalProductsCount: 132 + processedProductsCount: 132 + failedProductsCount: 0 + relationships: + results: + links: + related: https://www.ankorstore.com/api/v1/catalog/integrations/operations/90567710-de47-49e4-8536-aab80c1a469c/results + self: https://www.ankorstore.com/api/v1/catalog/integrations/operations/90567710-de47-49e4-8536-aab80c1a469c/relationships/results + links: + self: https://www.ankorstore.com/api/v1/catalog/integrations/operations/90567710-de47-49e4-8536-aab80c1a469c + '401': + description: Unauthorized + content: *ref_4 + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 + '500': + description: '[Server Error](https://jsonapi.org/format/#errors)' + content: *ref_7 + callbacks: + operationCallback: + '{$request.body#/data/attributes/callbackUrl}': + post: + summary: A callback triggered when events occur in the operation process + requestBody: + content: &ref_27 + application/json: + schema: + title: CallbackEvent + type: object + required: &ref_102 + - event + - topic + - occurredAt + properties: &ref_103 + event: + type: string + description: The name of the event that occurred + example: completed + topic: + type: string + description: | + The event category represented as a unique identifier of the event type. The topic is defined as a concatenation of the resource and event names `{$.data.type}.{$.event}`. You might use this topic as a partition key to distribute the callback events you receive to separate queues or pools of workers to process the callbacks asynchronously. + example: catalog-integration-operation.completed + occurredAt: + type: string + description: The date and time when event occurred + format: date-time + data: + description: the JSON:API resource describing the state of the entity which triggered the callback + title: Operation + type: object + required: *ref_25 + properties: *ref_26 + responses: + '200': + description: Acknowledge a successful delivery of the callback + /api/v1/catalog/integrations/operations/delete: + post: + summary: Create a deletion operation + description: | + Creates an Operation that deletes products from Ankorstore's catalog. The operation is started directly after creation. + operationId: create-delete-catalog-integration-operations + tags: + - Catalog Integrations + parameters: + - name: Accept + in: header + description: application/vnd.api+json + schema: *ref_3 + requestBody: + content: &ref_184 + application/vnd.api+json: + schema: + type: object + required: + - source + - callbackUrl + - products + properties: + source: + title: OperationSource + description: Source of the operation + type: string + enum: *ref_24 + callbackUrl: + type: string + description: | + The url of the endpoint that will be called when an operation completes. When an operation reaches a completed state such as **Success**, **Failed**, or **Partially Failed** the API platform will trigger a request to your endpoint. + products: + type: array + items: + type: object + properties: + type: + type: string + description: The type of resource to create + enum: + - catalog-integration-product + attributes: + type: object + properties: + external_id: + type: string + description: The external identifier of the product to delete + variants: + type: array + items: + type: object + properties: + sku: + type: string + description: The SKU of the product variant to delete + examples: + default: + value: &ref_179 + source: shopify + callbackUrl: https://callback.url/called/after/processing + products: + - type: catalog-integration-product + attributes: + external_id: '123456' + variants: + - sku: 123456-1 + - sku: 123456-2 + responses: + '201': + description: The operation that was successfully created + content: &ref_161 + application/vnd.api+json: + schema: + type: object + properties: + data: + title: Operation + description: An operation resource + type: object + required: *ref_25 + properties: *ref_26 + examples: + default: + value: &ref_180 + jsonapi: + version: '1.0' + links: + self: https://www.ankorstore.com/api/v1/catalog/integrations/operations/90567710-de47-49e4-8536-aab80c1a469c + data: + id: 90567710-de47-49e4-8536-aab80c1a469c + type: catalog-integration-operation + attributes: + source: shopify + status: started + operationType: delete + createdAt: '2024-01-01T14:15:22Z' + startedAt: '2024-01-01T15:27:22Z' + completedAt: null + callbackUrl: https://callback.url/called/after/processing + totalProductsCount: 132 + processedProductsCount: 0 + failedProductsCount: 0 + relationships: + results: + links: + related: https://www.ankorstore.com/api/v1/catalog/integrations/operations/90567710-de47-49e4-8536-aab80c1a469c/results + self: https://www.ankorstore.com/api/v1/catalog/integrations/operations/90567710-de47-49e4-8536-aab80c1a469c/relationships/results + links: + self: https://www.ankorstore.com/api/v1/catalog/integrations/operations/90567710-de47-49e4-8536-aab80c1a469c + '401': + description: Unauthorized + content: *ref_4 + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 + '500': + description: '[Server Error](https://jsonapi.org/format/#errors)' + content: *ref_7 + callbacks: + operationCallback: + '{$request.body#/data/attributes/callbackUrl}': + post: + summary: A callback triggered when events occur in the operation process + requestBody: + content: *ref_27 + responses: + '200': + description: Acknowledge a successful delivery of the callback + /api/v1/catalog/integrations/operations/{operationId}: + get: + summary: Retrieve an operation + description: Returns specific Operation resource data + operationId: get-catalog-integration-operation + tags: + - Catalog Integrations + parameters: + - name: Accept + in: header + description: application/vnd.api+json + schema: *ref_3 + - name: operationId + in: path + required: true + schema: &ref_29 + type: string + format: uuid + description: The unique identifier of the operation + responses: + '200': + description: The operation resource + content: *ref_28 + '404': + description: '[Not found](https://jsonapi.org/format/#fetching-resources-responses-404)' + content: *ref_21 + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 + '500': + description: '[Server Error](https://jsonapi.org/format/#errors)' + content: *ref_7 + patch: + summary: Patch Operation resource + description: Patch Operation resource + operationId: patch-catalog-integration-operation + tags: + - Catalog Integrations + parameters: + - name: Accept + in: header + description: application/vnd.api+json + schema: *ref_3 + - name: operationId + in: path + required: true + schema: *ref_29 + description: The unique identifier of the operation + requestBody: + content: &ref_185 + application/vnd.api+json: + schema: + type: object + properties: + data: + type: object + properties: + id: + type: string + description: The unique identifier of the operation to update + format: uuid + type: + type: string + description: The type of resource to be updated + enum: + - catalog-integration-operation + attributes: + type: object + properties: + status: + type: string + description: | + The operation status. Set this attribute to `started` in order to start processing the operation. Please note that an attempt to start processing an empty operation (i.e. an operation with no products attached) always leads to the operation being marked as "Skipped" and triggers the generation of an empty report. + Only one Operation is allowed to be started at a time. Any attempt of starting an Operation while another one is currently being processed (started, but not completed/cancelled yet) will result on a `pending` status. + Once an Operation processing has been completed, next `pending` one for the Brand will be executed automatically. + enum: + - started + examples: + default: + value: + data: + id: 90567710-de47-49e4-8536-aab80c1a469c + type: catalog-integration-operation + attributes: + status: started + responses: + '200': + description: The successfully updated operation + content: *ref_28 + '401': + description: Unauthorized + content: *ref_4 + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 + '500': + description: '[Server Error](https://jsonapi.org/format/#errors)' + content: *ref_7 + /api/v1/catalog/integrations/operations/{operationId}/products: + post: + summary: Add products to an operation + description: Add products data to an existing Operation resource + operationId: post-catalog-integration-operation-products + tags: + - Catalog Integrations + parameters: + - name: operationId + in: path + required: true + schema: *ref_29 + description: The unique identifier of the operation + - name: Accept + in: header + description: application/vnd.api+json + schema: *ref_3 + requestBody: + content: &ref_186 + application/vnd.api+json: + schema: + type: object + properties: + products: + type: array + items: + type: object + required: &ref_108 + - id + - type + properties: &ref_109 + id: + type: string + description: User-defined unique identifier of the product + type: + type: string + description: Type of resource + default: catalog-integration-product + attributes: + type: object + description: | + The product attributes. In case of a deletion operation, no attribute is expected. The only required information is the unique product identifier to delete (see following example). + ```json + { + "id": "", + "type": "catalog-integration-product" + } + ``` + properties: + external_id: + type: string + description: ID from external source + name: + type: string + description: Product name + tags: + type: array + description: List of product tags + items: + tag: + type: string + description: Tag name + enum: + - tags_fresh_product + - tags_frozen_product + - tags_organic + - tags_handmade + - tags_eco_friendly + - tags_zero_waste + - tags_cruelty_free + - tags_bestseller + - tags_vegan + - tags_contains_alcohol + main_image: + type: string + description: | + URL of the image that will be used as main one for the product + > It will have the number 1 order + images: + type: array + description: List of additional images for the product (Variants will inherit them) + items: + type: object + description: Image + properties: &ref_31 + order: + type: integer + description: | + Order number for the image to be shown + > Product Images: + > 1 belongs to main image + > Additional ones need to use 2 onwards + + > Variant Images: + > Will inherit from parent product if not provided + > Will be shown in the provided order + url: + type: string + description: URL of the image + hs_code: + type: string + description: HS code + currency: + type: string + description: Currency used in pricing + enum: + - GBP + - EUR + - SEK + vat_rate: + type: number + format: float + description: VAT rate + description: + type: string + description: | + Product description + > Must be at least 30 chars long + discount_rate: + type: number + format: float + description: | + Discount rate applied + > Must be between 0 and 100 + unit_multiplier: + type: number + format: integer + description: | + The minimum quantity in which a product is sold. When adding the product on the cart, cart price is computed by multiplying wholesale price * unit_multiplier + > Must be at least 1 + ankorstore_product_type_id: + type: number + format: integer + description: | + ID for Product Type as defined on Ankorstore taxonomy. When present it will be treated as truth and `external_product_type_id` will be kept as reference. For more information on available product types see [Ankorstore Taxonomy](https://docs.google.com/spreadsheets/d/1w7orca2KN-pb8HkGprOOLF5YdERmcQoUCRQY5kwCWkU/export?gid=0&format=csv) + external_product_type_id: + type: string + description: | + ID for Product Type as defined on the external source. When `ankorstore_product_type_id` is not present this will be tread as fallback to try and match the taxonomy from external source to Ankorstore taxonomy. This is not guaranteed, it is advised to always share directly the `ankorstore_product_type_id` to ensure product created will be contain the expected product type as desired and `external_product_type_id` kept as reference. + product_type_attributes: + type: array + description: Attributes of the product type + items: + anyOf: + - type: object + description: Age attribute + properties: &ref_104 + name: + type: string + description: Age group + enum: + - age_group + value: + type: string + description: Age group + enum: + - baby + - kids + - adult + - type: object + description: Gender attribute + properties: &ref_105 + name: + type: string + description: Target gender + enum: + - target_gender + value: + type: string + description: Gender + enum: + - unisex + - male + - female + wholesale_price: + type: number + format: float + description: Wholesale price + retail_price: + type: number + format: float + description: Retail price + made_in_country: + type: string + description: Country code in Alpha-2 format + shape_properties: + type: object + description: Shape properties of the item + properties: &ref_30 + dimensions: + type: object + description: Item dimensions + properties: + unit_code: + type: string + description: Unit of the measure + width: + type: number + format: float + description: Width + height: + type: number + format: float + description: height + length: + type: number + format: float + description: length + capacity: + type: object + description: Item capacity + properties: + unit_code: + type: string + description: Unit of the measure + amount: + type: number + format: float + description: Number of units of capacity + weight: + type: object + description: Item weight + properties: + unit_code: + type: string + description: Unit of the measure + amount: + type: number + format: float + description: Number of units of weight + variants: + type: array + description: | + Variant of the product + > Every product must have at least one variant > In the case of multiple variants, unique options should be provided for each of them + items: + type: object + description: Variant of the product + properties: &ref_107 + ian: + type: string + description: | + IAN code + > Must be exactly 13 chars long + sku: + type: string + description: SKU code + stock_quantity: + type: integer + description: Stock available, 0 means out of stock + is_always_in_stock: + type: boolean + description: If the product is always in stock, we will ignore the stock value + external_id: + type: string + description: ID for the variant from external source + discount_rate: + type: number + format: float + description: | + Discount rate applied + > Must be between 0 and 100 > Will be inherited from parent Product if not provided + retail_price: + type: number + format: float + description: | + Retail price + > Will be inherited from parent Product if not provided + wholesale_price: + type: number + format: float + description: | + Wholesale price + > Will be inherited from parent Product if not provided + shape_properties: + type: object + description: Shape properties of the item + properties: *ref_30 + options: + type: array + description: Options specific to the variant + items: + type: object + description: | + Specific options related to a variant + > Should not be provided in the case of having only one variant > Combination of values should be unique in the case of multiple variants + properties: &ref_106 + name: + type: string + description: Name of the property + enum: + - color + - size + - material + - style + value: + type: string + description: Value for the option name + images: + type: array + description: | + Images related to specific variant. Will be shown after the ones inherited from parent product in the provided order. + items: + type: object + description: Image + properties: *ref_31 + examples: + default: + value: &ref_181 + products: + - id: a12aef05-7c20-4efb-a336-ea53be904d0e + type: catalog-integration-product + attributes: + external_id: a12aef05-7c20-4efb-a336-ea53be904d0e + name: Example product 1 + tags: + - tags_fresh_product + - tags_frozen_produc + - tags_organic + - tags_handmade + - tags_eco_friendly + - tags_zero_waste + - tags_cruelty_free + - tags_bestseller + - tags_vegan + - tags_contains_alcohol + main_image: https://url.of/product_main_image.png + images": + - order: 2 + url: https://image.2/ + - order: 3 + url: https://image.3/ + - order: 4 + url: https://image.4/ + hs_code: '123456' + currency: EUR + vat_rate: 20 + description: This is an example of product description received in the payload. + discount_rate: 0 + unit_multiplier: 1 + ankorstore_product_type_id: 6289 + external_product_type_id: 73098f20-63f6-41b6-8cc6-8b55104873d8 + product_type_attributes: + - name: age_group + value: kids + - name: target_gender + value: unisex + retail_price: 25 + wholesale_price: 20 + made_in_country: ES + shape_properties: + dimensions: + unit_code: cm + width: 10 + height: 10 + length: 10 + capacity: + unit_code: L + amount: 1 + weight: + unit_code: kg + amount: 1 + variants: + - ian: '1234567890123' + sku: Example SKU + stock_quantity: 100 + is_always_in_stock: false + external_id: 747476f8-e268-4fab-9788-7f7752f61095 + discount_rate: 0 + retail_price: 25 + wholesale_price: 20 + shape_properties: + dimensions: + unit_code: cm + width: 10 + height: 10 + length: 10 + capacity: + unit_code: L + amount: 1 + weight: + unit_code: kg + amount: 1 + options: + - name: size + value: XXL + - name: color + value: blue + images: + - order: 1 + url: https://image.1/ + - order: 2 + url: https://image.2/ + - order: 3 + url: https://image.3/ + responses: + '200': + description: The products were successfully added to the operation + content: &ref_162 + application/vnd.api+json: + schema: + type: object + properties: + meta: + type: object + properties: + totalProductsCount: + type: integer + description: The total number of products attached to the operation + examples: + default: + value: + jsonapi: + version: '1.0' + meta: + totalProductsCount: 104 + '401': + description: Unauthorized + content: *ref_4 + '403': + description: '[Forbidden](https://jsonapi.org/format/#crud-creating-responses-403)' + content: *ref_20 + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 + '500': + description: '[Server Error](https://jsonapi.org/format/#errors)' + content: *ref_7 + /api/v1/catalog/integrations/operations/{operationId}/results: + get: + summary: Retrieve an operation report + description: | + Once an operation is completed, an execution report is generated. This report summarises the result of the operation execution for each of its products. + operationId: get-catalog-integration-operation-report + tags: + - Catalog Integrations + parameters: + - name: operationId + in: path + required: true + schema: *ref_29 + description: The unique identifier of the operation + - name: Accept + in: header + description: application/vnd.api+json + schema: *ref_3 + - name: page[limit] + in: query + description: limit the amount of results returned + required: false + schema: *ref_32 + - name: page[before] + in: query + description: show items before the provided ID (uuid format) + required: false + schema: *ref_33 + - name: page[after] + in: query + description: show items after the provided ID (uuid format) + required: false + schema: *ref_34 + responses: + '200': + description: The execution result of the operation + content: + application/vnd.api+json: + schema: + title: Product Integration Resource list + description: Product Integration Resource list + type: object + additionalProperties: false + properties: &ref_113 + jsonapi: + description: An object describing the server's implementation + type: object + properties: *ref_0 + additionalProperties: false + data: + type: array + items: + title: OperationResult + type: object + required: &ref_111 + - id + - type + properties: &ref_112 + id: + type: string + format: uuid + description: A globally-unique identifier for the result + readOnly: true + type: + type: string + default: catalog-integration-result + description: Type of resource object + readOnly: true + attributes: + type: object + required: + - externalProductId + - status + properties: + externalProductId: + type: string + description: User-defined unique identifier of the product. May become "undefined" if the error concerns to the entire operation + status: + type: string + description: The operation execution result for this product + enum: + - success + - failure + failureReason: + type: + - string + - 'null' + description: The reason for the failure if the operation processing failed + issues: + description: List of related issues found when processing - Only validation issues are exposed + type: array + items: + type: object + properties: &ref_110 + field: + type: string + description: Property name + reason: + type: string + description: Reason of the validation failure + enum: + - required_field + - invalid_field + - invalid_image + - internal_error + message: + type: string + description: Details related to the validation failure + meta: + type: object + description: Meta with Pagination Details + required: *ref_17 + additionalProperties: true + properties: *ref_18 + links: + description: Pagination navigation links. If a link does not exist then you cannot paginate any further in that direction. + type: object + properties: *ref_19 + examples: + example: + value: &ref_182 + meta: + page: + from: 29c60b89-0fb6-4bd9-9c1e-2d312cf141e3 + hasMore: true + perPage: 100 + to: 03dcf453-b9d3-4cc7-be24-b0e0f0453fb2 + jsonapi: + version: '1.0' + links: + first: https://www.ankorstore.com/api/v1/catalog/integrations/3de86ffd-aa50-49e2-b178-e2ffd6e6f0e5/products?include=&page%5Blimit%5D=2 + next: https://www.ankorstore.com/api/v1/catalog/integrations/3de86ffd-aa50-49e2-b178-e2ffd6e6f0e5/products?include=&page%5Bafter%5D=797910&page%5Blimit%5D=2 + prev: https://www.ankorstore.com/api/v1/catalog/integrations/3de86ffd-aa50-49e2-b178-e2ffd6e6f0e5/products?include=&page%5Bbefore%5D=904234&page%5Blimit%5D=2 + data: + - id: a830fb5a-c2f9-4227-a46a-4e1c72b5f4c1 + type: catalog-integration-result + attributes: + externalProductId: fab0ccb6-2e5c-484e-994d-05475b54a013 + status: success + failureReason: null + issues: [] + - id: a52bdb84-8d4c-49f6-9457-6aafda51abda + type: catalog-integration-result + attributes: + externalProductId: 07734e55-ca17-4bb3-8f1d-e6d957270d7d + status: failure + failureReason: validation_error + issues: + - field: product_type_id + reason: required_field + message: Product type must be provided + - field: variants[0].sku + reason: required_field + message: Variant SKU is required + - field: variants[0].ian + reason: invalid_field + message: This value should have exactly 13 characters + - id: 1cd7c89c-9428-44c5-9a77-9448467453c3 + type: catalog-integration-result + attributes: + externalProductId: 8d290277-b40e-4d53-98b8-c65b251fedae + status: success + failureReason: null + issues: [] + - id: 2246214c-f7b8-4d84-8fd4-de957c192b9a + type: catalog-integration-result + attributes: + externalProductId: ecfcb82c-3178-46ef-805f-1cdf2c22b14a + status: failure + failureReason: validation_error + issues: + - field: product_type_id + reason: required_field + message: Product type must be provided + - field: variants[0].sku + reason: required_field + message: Variant SKU is required + - field: variants[0].ian + reason: invalid_field + message: This value should have exactly 13 characters + - id: a830fb5a-c2f9-4227-a46a-4e1c72b5f4c2 + type: catalog-integration-result + attributes: + externalProductId: unknown + status: failure + failureReason: internal_error + issues: + - message: This is an internal error, that should not have happened. Please contact support team. + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 + '500': + description: '[Server Error](https://jsonapi.org/format/#errors)' + content: *ref_7 + /api/v1/integration/external-integrations/-actions/update-status: + post: + summary: Update status of External Integration + operationId: integration-update-external-integration-status + description: Allows to notify Ankorstore about changing the status of an integration of external platform + tags: + - Integration + parameters: + - name: Accept + in: header + description: application/vnd.api+json + schema: *ref_3 + requestBody: + required: true + content: &ref_187 + application/json: + schema: + type: object + properties: &ref_35 + platform: + type: string + enum: + - shopify + - woocommerce + - prestashop + - odoo + - sellsy + status: + type: string + enum: + - enabled + - disabled + required: &ref_36 + - platform + - status + responses: + '200': + description: Single External Integration + content: &ref_163 + application/vnd.api+json: + schema: + type: object + properties: + jsonapi: + description: An object describing the server's implementation + type: object + properties: *ref_0 + additionalProperties: false + data: + type: object + properties: &ref_114 + type: + type: string + description: '[resource object type](https://jsonapi.org/format/#document-resource-object-identification)' + id: + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + attributes: + type: object + properties: *ref_35 + required: *ref_36 + required: + - data + - jsonapi + '400': + description: Bad request + content: &ref_48 + application/vnd.api+json: + schema: + type: object + additionalProperties: false + properties: *ref_1 + required: *ref_2 + example: + jsonapi: + version: '1.0' + errors: + - detail: Bad request + status: '400' + '401': + description: Unauthorized + content: *ref_4 + '403': + description: '[Forbidden](https://jsonapi.org/format/#crud-creating-responses-403)' + content: *ref_20 + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 + '422': + description: 'Unprocessable Entity : Data provided are invalid' + content: &ref_64 + application/vnd.api+json: + schema: + type: object + additionalProperties: false + properties: *ref_1 + required: *ref_2 + example: + jsonapi: + version: string + errors: + - detail: The field is required. + source: + pointer: data.attributes.field + status: '422' + title: Unprocessable Content + '500': + description: '[Server Error](https://jsonapi.org/format/#errors)' + content: *ref_7 + /api/v1/brands/me: + get: + summary: Get own brand details + operationId: get-api-v1-own-brands + description: Get own brand details + parameters: + - name: Accept + in: header + description: application/vnd.api+json + schema: *ref_3 + tags: + - Brands + responses: + '200': + description: Single Brand resource response + content: &ref_164 + application/vnd.api+json: + schema: + type: object + required: + - jsonapi + - data + properties: + jsonapi: + description: An object describing the server's implementation + type: object + properties: *ref_0 + additionalProperties: false + data: + type: array + items: + type: object + required: + - id + - type + - attributes + properties: + id: + type: string + format: uuid + type: + type: string + attributes: + type: object + properties: + automationMode: + type: string + enum: + - automatic-brand_control + - automatic-confirm-and-request-fulfillment + '401': + description: Unauthorized + content: *ref_4 + '403': + description: '[Forbidden](https://jsonapi.org/format/#crud-creating-responses-403)' + content: *ref_20 + '404': + description: '[Not found](https://jsonapi.org/format/#fetching-resources-responses-404)' + content: *ref_21 + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 + /api/v1/master-orders: + get: + summary: List Master Orders + description: Retrieve a list of Master Orders + operationId: list-master-orders + tags: + - Ordering + parameters: + - name: include + in: query + allowEmptyValue: true + required: false + schema: &ref_38 + type: string + enum: + - internalOrder + - externalOrder + - shipment + - name: Accept + in: header + description: application/vnd.api+json + schema: *ref_3 + - name: page[limit] + in: query + description: limit the amount of results returned + required: false + schema: *ref_32 + - name: page[before] + in: query + description: show items before the provided ID (uuid format) + required: false + schema: *ref_33 + - name: page[after] + in: query + description: show items after the provided ID (uuid format) + required: false + schema: *ref_34 + responses: + '200': + description: '[OK](https://jsonapi.org/format/#fetching-resources-responses-200)' + content: + application/vnd.api+json: + schema: + title: Master Order List + type: object + additionalProperties: false + properties: &ref_120 + data: + type: array + items: + title: Master Order + type: object + additionalProperties: false + properties: &ref_39 + type: + type: string + description: '[resource object type](https://jsonapi.org/format/#document-resource-object-identification)' + id: + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + relationships: + type: object + additionalProperties: false + properties: + internalOrder: + type: object + required: + - data + properties: + data: + type: object + required: + - type + - id + properties: + type: + type: string + description: '[resource object type](https://jsonapi.org/format/#document-resource-object-identification)' + id: + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + externalOrder: + type: object + required: + - data + properties: + data: + type: object + required: + - type + - id + properties: + type: + type: string + description: '[resource object type](https://jsonapi.org/format/#document-resource-object-identification)' + id: + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + shipment: + type: object + required: + - data + properties: + data: + type: object + required: + - type + - id + properties: + type: + type: string + description: '[resource object type](https://jsonapi.org/format/#document-resource-object-identification)' + id: + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + included: + description: One of the included resources + type: array + items: + anyOf: + - description: The resource object for Order + type: object + additionalProperties: false + title: Order Resource + properties: &ref_40 + type: + type: string + description: '[resource object type](https://jsonapi.org/format/#document-resource-object-identification)' + id: + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + attributes: + type: object + additionalProperties: false + properties: + masterOrderId: + type: string + description: The identifier of the linked master order + format: uuid + status: + type: string + example: ankor_confirmed + enum: &ref_44 + - ankor_confirmed + - rejected + - brand_confirmed + - shipping_labels_generated + - fulfillment_requested + - shipped + - reception_refused + - received + - invoiced + - brand_paid + - cancelled + reference: + type: integer + description: The order reference used on shipping labels, communication etc + brandCurrency: + type: string + description: The currency the brand is paid in + brandNetAmount: + description: The amount the brand is paid (total - fees - shipping cost + shipping refund). You may find the Ankorstore fees and the other amounts by including the orders billing items. + type: integer + brandTotalAmount: + description: The total of all order items not including VAT + type: integer + brandTotalAmountVat: + description: The total VAT of all order items + type: integer + brandTotalAmountWithVat: + description: The total of all order items including VAT + type: integer + shippingMethod: + type: + - 'null' + - string + description: The chosen shipping method after going through the shipping process + enum: + - ankorstore + - custom + - null + shippingOverview: + title: Order Resource -> Shipping Overview + description: Contains all information related to either shipping method (`ankorstore` or `custom`). This field is ONLY included when fetching a single order at a time. + type: object + properties: &ref_117 + availableShippingMethods: + type: array + description: Available shipping methods to use. Custom is ship with your own carrier outside of Ankorstore. + items: + enum: + - ankorstore + - custom + shipToAddress: + type: object + description: The address the order needs to be shipped to + required: + - street + - city + - postalCode + properties: + name: + type: + - 'null' + - string + description: The first and last name of the recipient + organisationName: + type: + - 'null' + - string + description: The organisational name of the recipient + street: + type: + - 'null' + - string + city: + type: + - 'null' + - string + postalCode: + type: + - 'null' + - string + countryCode: + type: + - 'null' + - string + expectedShippingDates: + type: object + description: The minimum and maximum expected shipping dates + required: + - minimum + - maximum + properties: + minimum: + type: string + format: datetime + maximum: + type: string + format: datetime + provider: + type: + - 'null' + - string + description: The company providing the shipping service + enum: + - ups + - tnt + - gls + - dpd + - dhl + - dhl_express + - colissimo + - chronopost + - null + tracking: + type: + - 'null' + - object + description: Tracking details of the order + properties: + number: + type: string + link: + type: string + format: url + description: A URL to view the tracking status + latestQuote: + description: |- + The quote is the price of the parcel(s) shipping. + If this object is null then no quote has been generated. + type: + - 'null' + - object + properties: + id: + type: string + description: Id of the last quote generated. Every time a ship call is done, a new calculation is made based on parcels dimensions and weight sent + provider: + type: string + enum: + - custom + - ups + description: |- + Provider responsible for the calculation. If custom, the calculation is done by Ankorstore and refunded. + If any other, the calculation is done by the provider and the shipping price is covered by Ankorstore (most of the case, see shippingCostsOverview section). + rateProvider: + type: string + description: The provider of the rate for `rateAmount`. + enum: + - ups + - ankorstore + rateAmount: + type: object + description: Amount calculated for the parcels provided. + properties: + amount: + type: integer + description: Lowest denomination of the currency this amount belongs to. + currency: + type: string + shippingCostsOverview: + type: object + description: Overview of costs related to shipping. This object is displayed only if a shipping cost fee or a refund exists + properties: + amount: + type: integer + description: Lowest denomination of the currency this amount belongs to. + currency: + type: string + type: + type: string + enum: + - refund + - fee + description: |- + Type of shipping costs: + If type = `refund` the amount will be refunded to the brand (added to brand net amount). + if type = `fee` the amount will be subtracted from brand net amount as a contribution to shipping costs. + required: + - id + - provider + parcels: + type: array + uniqueItems: true + items: + description: Shipping Label Parcel + type: object + properties: &ref_115 + length: + type: integer + maximum: 274 + width: + type: integer + maximum: 274 + height: + type: integer + maximum: 274 + distanceUnit: + type: string + description: The unit of distance + enum: &ref_66 + - cm + weight: + type: integer + minimum: 1 + maximum: 30000 + massUnit: + type: string + description: The unit of mass + enum: &ref_67 + - g + trackedPackage: + type: + - 'null' + - object + description: The tracking per parcel + properties: + labelUrl: + description: The URL to download the shipping label + type: + - 'null' + - string + format: url + eta: + type: + - 'null' + - string + format: datetime + trackingNumber: + type: string + trackingLink: + type: string + currentStatus: + type: object + properties: &ref_37 + status: + type: string + description: The current status of the order/parcel + enum: + - UNKNOWN + - PRE_TRANSIT + - DELIVERED + - RETURNED + - FAILURE + statusDetails: + description: Human readable version of status + type: + - string + - 'null' + updatedAt: + type: string + description: Last time the status was updated + format: datetime + location: + type: object + description: Last known location + properties: + city: + type: + - 'null' + - string + state: + type: + - 'null' + - string + zip: + type: + - 'null' + - string + country: + type: + - 'null' + - string + required: + - labelUrl + - eta + - trackingLink + - currentStatus + required: &ref_116 + - length + - width + - height + - distanceUnit + - weight + - massUnit + - trackedPackage + transaction: + type: + - 'null' + - object + properties: + pickup: + description: The scheduled pickup, requires an API call to be made after the shipping labels have been generated. + type: + - 'null' + - object + required: + - pickupDate + - closeTime + - readyTime + - externalReferenceId + properties: + pickupDate: + type: string + format: datetime + description: The date of the pickup + readyTime: + type: string + description: 'Opening time of pickup Eg: 10:00:00' + closeTime: + type: string + description: 'Close time (pickup required to happen before this time) Eg: 13:00:00' + externalReferenceId: + type: string + description: The reference number for this pickup + tracking: + description: The tracking details for the overall shipment + type: object + properties: + eta: + type: + - 'null' + - string + format: datetime + description: The estimated time of arrival for the order + trackingNumber: + type: string + description: The tracking number of the order + trackingLink: + type: string + format: url + description: The tracking link for the order + currentStatus: + type: object + properties: *ref_37 + required: + - pickup + - tracking + required: &ref_118 + - availableShippingMethods + - shipToAddress + - expectedShippingDates + brandRejectReason: + type: + - 'null' + - string + description: The reason the brand has given for rejecting the order + retailerRejectReason: + type: + - 'null' + - string + description: The reason the retailer rejected the reception of the order + retailerCancellationRequestReason: + type: + - 'null' + - string + description: The reason the retailer has given for a cancellation request + billingName: + type: + - 'null' + - string + description: The billing address name + billingOrganisationName: + type: + - 'null' + - string + description: The billing address organisation name + billingStreet: + type: + - 'null' + - string + description: The billing address street name + billingPostalCode: + type: + - 'null' + - string + description: The billing address postal code + billingCity: + type: + - 'null' + - string + description: The billing address city + billingCountryCode: + type: + - 'null' + - string + description: The billing address country code - ISO format + submittedAt: + type: string + format: datetime + description: The timestamp of when the order was submitted (order is placed) + shippedAt: + type: + - 'null' + - string + format: datetime + description: The timestamp of when the order was shipped + brandPaidAt: + type: + - 'null' + - string + format: datetime + description: The timestamp of when the brand was paid + createdAt: + type: string + format: datetime + description: (deprecated) The timestamp of when the order was created (before retailer payment) + updatedAt: + type: string + format: datetime + description: The timestamp of when the order was updated (does not include other resources) + relationships: + type: object + properties: + retailer: + description: Related Retailer Resource + type: object + properties: + data: + allOf: + - description: Resource identification present in Resource Objects and Resource Identifier Objects. + type: object + required: *ref_12 + properties: *ref_13 + additionalProperties: false + - type: object + properties: + type: + const: retailers + billingItems: + description: Related Billing Item Resources + type: object + properties: + data: + type: array + uniqueItems: true + items: + allOf: + - description: Resource identification present in Resource Objects and Resource Identifier Objects. + type: object + required: *ref_12 + properties: *ref_13 + additionalProperties: false + - type: object + properties: + type: + const: billing-items + orderItems: + description: Related Order Item Resources + type: object + properties: + data: + type: array + uniqueItems: true + items: + allOf: + - description: Resource identification present in Resource Objects and Resource Identifier Objects. + type: object + required: *ref_12 + properties: *ref_13 + additionalProperties: false + - type: object + properties: + type: + const: order-items + orderItems-productOption: + description: 'Schema: Order Item -> Product Option Resource' + type: object + properties: + data: + description: Resource identification present in Resource Objects and Resource Identifier Objects. + type: object + required: *ref_12 + properties: *ref_13 + additionalProperties: false + orderItems-productOption-product: + description: 'Schema: Order Item -> Product Option Resource -> Product' + type: object + properties: + data: + description: Resource identification present in Resource Objects and Resource Identifier Objects. + type: object + required: *ref_12 + properties: *ref_13 + additionalProperties: false + orderItems-productVariant: + description: 'Schema: Order Item -> Product Variant Resource' + type: object + properties: + data: + description: Resource identification present in Resource Objects and Resource Identifier Objects. + type: object + required: *ref_12 + properties: *ref_13 + additionalProperties: false + orderItems-productVariant-product: + description: 'Schema: Order Item -> Product Variant Resource -> Product' + type: object + properties: + data: + description: Resource identification present in Resource Objects and Resource Identifier Objects. + type: object + required: *ref_12 + properties: *ref_13 + additionalProperties: false + required: &ref_41 + - type + - id + - type: object + title: External Order Resource + description: The resource object for External Order + additionalProperties: false + properties: &ref_42 + type: + type: string + description: '[resource object type](https://jsonapi.org/format/#document-resource-object-identification)' + id: + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + attributes: + type: object + additionalProperties: false + required: + - status + - shippingAddress + properties: + status: + type: string + description: Status of the order. + shippingAddress: + type: object + description: Shipping address of the recipient. + required: + - firstName + - lastName + - email + - phoneNumber + - company + - street + - city + - countryCode + - postalCode + properties: + firstName: + type: string + description: First name of the person, receiving the order + lastName: + type: string + description: Last name of the person, receiving the order + email: + type: string + format: email + description: Email of the person, receiving the order + phoneNumber: + type: string + description: Phone number of the person, receiving the order. + company: + type: + - 'null' + - string + description: Name of the company. + street: + type: string + description: Street address of the destination place. + city: + type: string + description: Name of the destination city. + postalCode: + type: string + description: Postal code of the destination place. + countryCode: + type: string + description: ISO 3166-1 country code. + - title: Order shipment + type: object + additionalProperties: false + properties: &ref_119 + type: + type: string + description: '[resource object type](https://jsonapi.org/format/#document-resource-object-identification)' + id: + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + attributes: + type: object + additionalProperties: false + required: + - shippedAt + - trackingNumber + - shippingCarrier + - trackingUrl + properties: + shippedAt: + type: + - 'null' + - string + format: date-time + trackingNumber: + type: + - 'null' + - string + shippingCarrier: + type: + - 'null' + - string + trackingUrl: + type: + - 'null' + - string + '401': + description: Unauthorized + content: *ref_4 + '404': + description: '[Not found](https://jsonapi.org/format/#fetching-resources-responses-404)' + content: *ref_21 + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 + /api/v1/master-orders/{master_order}: + get: + summary: Get Master Order + description: Retrieve a specific Master Order + operationId: get-master-order + tags: + - Ordering + parameters: + - name: Accept + in: header + description: application/vnd.api+json + schema: *ref_3 + - name: master_order + in: path + required: true + schema: &ref_158 + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + - name: include + in: query + allowEmptyValue: true + required: false + schema: *ref_38 + responses: + '200': + description: '[OK](https://jsonapi.org/format/#fetching-resources-responses-200)' + content: + application/vnd.api+json: + schema: + title: Master Order Get + type: object + additionalProperties: false + properties: &ref_121 + data: + title: Master Order + type: object + additionalProperties: false + properties: *ref_39 + included: + description: One of the included resources + type: array + items: + anyOf: + - description: The resource object for Order + type: object + additionalProperties: false + title: Order Resource + properties: *ref_40 + required: *ref_41 + - type: object + title: External Order Resource + description: The resource object for External Order + additionalProperties: false + properties: *ref_42 + '401': + description: Unauthorized + content: *ref_4 + '404': + description: '[Not found](https://jsonapi.org/format/#fetching-resources-responses-404)' + content: *ref_21 + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 + /api/v1/master-orders/{orderId}/fulfillment-orders: + get: + summary: List Master Order Fulfillments Relationships + description: Retrieve a list of fulfillment relationships for a Master Order + operationId: ordering-master-orders-relationships-fulfillment-orders + tags: + - Ordering + parameters: + - name: Accept + in: header + description: application/vnd.api+json + schema: *ref_3 + - name: orderId + in: path + required: true + schema: + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + responses: + '200': + description: Set of fulfillment orders + content: &ref_165 + application/vnd.api+json: + schema: + type: object + properties: + data: + type: array + items: + properties: &ref_70 + type: + type: string + description: '[resource object type](https://jsonapi.org/format/#document-resource-object-identification)' + id: + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + attributes: + type: object + properties: &ref_127 + reference: + description: Unique human readable reference for the fulfillment order, used for communication with the warehouse + type: string + pattern: ^O_[0-9]{1,18}|[A-HJ-NP-TV-Z2-9]+$ + status: + type: string + enum: &ref_43 + - internal + - requested + - created + - scheduled + - released + - shipped + - cancelled + readOnly: true + createdAt: + type: string + format: date-time + readOnly: true + items: + type: array + items: + type: object + properties: &ref_122 + fulfillmentItemId: + type: string + format: uuid + quantity: + type: integer + description: quantity in batches + lotNumber: + type: + - 'null' + - string + expiryDate: + type: + - 'null' + - string + format: date-time + required: &ref_123 + - fulfillmentItemId + - quantity + shippedItems: + type: array + items: + type: object + properties: &ref_124 + fulfillableId: + type: string + format: uuid + batchQuantity: + type: integer + unitQuantity: + type: integer + lotNumber: + type: + - 'null' + - string + expiryDate: + type: + - 'null' + - string + format: date-time + required: &ref_125 + - fulfillableId + - batchQuantity + - unitQuantity + recipientType: + type: string + enum: &ref_126 + - consumer + - business + default: business + description: The type of recipient for a fulfillment order + required: &ref_128 + - shippingAddress + - items + links: + type: object + properties: + order: + type: string + relationships: + type: object + properties: + statusUpdates: + type: object + properties: + data: + description: An array of objects each containing `type` and `id` members for to-many relationships. + type: array + items: *ref_9 + uniqueItems: true + required: &ref_71 + - type + - id + - attributes + jsonapi: + description: An object describing the server's implementation + type: object + properties: *ref_0 + additionalProperties: false + included: + type: array + items: + anyOf: + - properties: &ref_72 + type: + type: string + description: '[resource object type](https://jsonapi.org/format/#document-resource-object-identification)' + id: + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + attributes: + description: Fulfillment order status update + type: object + properties: &ref_129 + status: + type: string + enum: *ref_43 + readOnly: true + receivedAt: + type: string + format: date-time + readOnly: true + required: + - data + - jsonapi + '401': + description: Unauthorized + content: *ref_4 + '404': + description: '[Not found](https://jsonapi.org/format/#fetching-resources-responses-404)' + content: *ref_21 + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 + /api/v1/master-orders/{orderId}/relationships/fulfillment-orders: + get: + summary: List Master Order Fulfillments + description: Retrieve a list of fulfillments for a Master Order + operationId: ordering-master-orders-relationship-fulfillment-orders + tags: + - Ordering + parameters: + - name: Accept + in: header + description: application/vnd.api+json + schema: *ref_3 + - name: orderId + in: path + required: true + schema: + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + responses: + '200': + description: Set of fulfillment order id and links + content: &ref_166 + application/vnd.api+json: + schema: + type: object + properties: + data: + description: An array of objects each containing `type` and `id` members for to-many relationships. + type: array + items: *ref_9 + uniqueItems: true + jsonapi: + description: An object describing the server's implementation + type: object + properties: *ref_0 + additionalProperties: false + required: + - data + - jsonapi + '401': + description: Unauthorized + content: *ref_4 + '404': + description: '[Not found](https://jsonapi.org/format/#fetching-resources-responses-404)' + content: *ref_21 + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 + /api/v1/orders: + get: + summary: List Internal Orders + description: Retrieve a list of Internal Orders + operationId: list-internal-orders + tags: + - Ordering + parameters: + - name: Accept + in: header + description: application/vnd.api+json + schema: *ref_3 + - name: filter[retailer] + in: query + description: Retailer Id + allowEmptyValue: true + required: false + schema: + type: string + example: 23e4567-e89b-12d3-a456-426614174000 + - name: filter[status] + in: query + description: Order Status + allowEmptyValue: true + required: false + schema: + type: string + example: ankor_confirmed + enum: *ref_44 + - name: page[limit] + in: query + description: limit the amount of results returned + required: false + schema: *ref_32 + - name: page[before] + in: query + description: show items before the provided ID (uuid format) + required: false + schema: *ref_33 + - name: page[after] + in: query + description: show items after the provided ID (uuid format) + required: false + schema: *ref_34 + responses: + '200': + description: '[OK](https://jsonapi.org/format/#fetching-resources-responses-200)' + content: + application/vnd.api+json: + schema: + title: Order Collection + type: object + required: &ref_130 + - data + properties: &ref_131 + data: + description: List of Order resource objects + type: array + uniqueItems: true + items: + description: The resource object for Order + type: object + additionalProperties: false + title: Order Resource + properties: *ref_40 + required: *ref_41 + included: + description: To reduce the number of HTTP requests, servers **MAY** allow responses that include related resources along with the requested primary resources. Such responses are called `compound documents`. + type: array + items: + anyOf: + - title: Retailer Resource + type: object + additionalProperties: false + example: &ref_49 + type: retailer + id: 092b63ce-c5b9-1eca-b05f-0242ac170007 + attributes: + companyName: null + storeName: TEST RETAILER + storeUrl: null + email: retailer@example.com + firstName: John + lastName: Smith + taxNumber: '12345678' + vatNumber: FR123456789 + eoriNumber: null + phoneNumberE164: '+3345656456456' + businessIdentifier: '3454353455' + createdAt: '2020-06-19T11:59:30.000000Z' + updatedAt: '2020-06-21T15:27:39.000000Z' + properties: &ref_50 + type: + type: string + description: '[resource object type](https://jsonapi.org/format/#document-resource-object-identification)' + id: + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + attributes: + type: object + properties: + companyName: + type: + - string + - 'null' + description: The registered company of the retailer + storeName: + type: string + description: The name of the store + storeUrl: + type: + - string + - 'null' + format: url + description: The store's website + email: + type: string + format: email + description: Contact email for the retailer + firstName: + type: string + description: Retailer's first name + lastName: + type: string + description: Retailer's last name + taxNumber: + type: string + description: Retailer's tax number + vatNumber: + type: string + description: Retailer's VAT number + eoriNumber: + type: + - string + - 'null' + description: Retailer's EORI number + phoneNumberE164: + type: string + description: Retailer's phone number (E164 format) + businessIdentifier: + type: string + description: The tax field to use - tax or vat number. If the retailer is a sole trader, this field will instead be their sole trading number + createdAt: + type: string + format: datetime + description: The timestamp when the retailer was created + updatedAt: + type: string + format: datetime + description: The timestamp when the retailer was updated + relationships: + type: object + properties: + orders: + description: The order's belonging to a retailer. See [Order Resource](https://ankorstore.github.io/api-docs/#tag/Order/operation/list-orders) + type: object + properties: + data: + description: An array of objects each containing `type` and `id` members for to-many relationships. + type: array + items: *ref_9 + uniqueItems: true + required: &ref_51 + - type + - id + - attributes + - title: Order Item Resource + type: object + additionalProperties: false + examples: &ref_52 + - type: order-items + id: 62b263a8-00e1-1ecb-98d2-0242ac170007 + attributes: + brandCurrency: EUR + quantity: 1 + multipliedQuantity: 12 + vatRate: 5.5 + brandAmount: 3996 + brandAmountVat: 220 + brandAmountWithVat: 4216 + brandUnitPrice: 333 + createdAt: '2022-02-02T19:43:14.000000Z' + updatedAt: '2022-02-02T19:43:14.000000Z' + relationships: + productOption: + data: + type: productOption + id: '114135' + properties: &ref_53 + type: + type: string + description: '[resource object type](https://jsonapi.org/format/#document-resource-object-identification)' + id: + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + attributes: + type: object + properties: + brandCurrency: + type: string + description: The currency of the amounts for the brand + quantity: + type: integer + description: The ordered quantity of the product + multipliedQuantity: + type: integer + description: Some products are sold in fixed quantities, e.g a case of 6 wine bottles. If the quantity was 2, the multiplied quantity of wine bottles would be 12 (6 x 2). This "unitMultiplier" can be found on the product. + vatRate: + type: number + format: float + description: The VAT percentage rate of the order item (0-100) + brandAmount: + description: The amount due to the brand for this item + type: integer + brandAmountVat: + description: The VAT amount due to the brand for this item + type: integer + brandAmountWithVat: + description: The amount + VAT due to the brand for this item + type: integer + brandUnitPrice: + description: The cost of a single unit of this item + type: integer + createdAt: + type: string + format: datetime + description: The timestamp this order item was created + updatedAt: + type: string + format: datetime + description: The timestamp this order item was updated + relationships: + type: object + properties: + productOptions: + description: 'Reference: Product Option Resource' + type: object + properties: + data: + description: An array of objects each containing `type` and `id` members for to-many relationships. + type: array + items: *ref_9 + uniqueItems: true + meta: + description: Non-standard meta-information that can not be represented as an attribute or relationship. + type: object + additionalProperties: true + required: &ref_54 + - type + - id + - title: Billing Item Resource + type: object + additionalProperties: false + examples: &ref_55 + - type: billing-items + id: f1dd6498-c5f8-1eca-a6b7-0242ac170007 + attributes: + type: brand_platform_fees + currency: EUR + vatRate: 20 + currencyRate: 1 + amount: -1259 + amountVat: -252 + amountWithVat: -1511 + createdAt: '2022-02-02T19:42:32.000000Z' + updatedAt: '2022-02-02T20:15:06.000000Z' + properties: &ref_56 + type: + type: string + description: '[resource object type](https://jsonapi.org/format/#document-resource-object-identification)' + id: + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + attributes: + type: object + properties: + type: + description: | + The `brand_platform_fees` is a commission for using our platform. It will be a negative amount which reduces the total amount paid to the brand. + + The `brand_new_customer_fees` is a commission on the first Order between brand and retailer. It will be a negative amount which reduces the total amount paid to the brand. + + The `brand_payment_fees` is a commission to guarantee Payment for brand. It will be a negative amount which reduces the total amount paid to the brand. + + The `brand_fast_payment` is a commission for using our fast payment feature. It will be a negative amount which reduces the total amount paid to the brand. + + The `brand_flat_shipping_fees` is the shipping cost collected from the retailer when the order is below brand Franco. It is positive and adds to the total amount paid. + + The `brand_shipping_fees` is a shipping cost. This type reduces the amount paid to the brand (but will be a positive value). + + The `brand_shipping_fees_refund` is a refund from Ankorstore to brand for shipping. This type is positive and adds to the total amount paid. + + The `brand_shipping_fees_discount` is a referral shipping offer. This type is positive and adds to the total amount paid. + + There still might also be legacy types which are not listed here but they will be removed in the nearest future. + type: string + enum: + - brand_platform_fees + - brand_new_customer_fees + - brand_payment_fees + - brand_fast_payment + - brand_flat_shipping_fees + - brand_shipping_fees + - brand_shipping_fees_refund + - brand_shipping_fees_discount + currency: + type: string + description: The currency of the billing item + vatRate: + type: number + format: float + description: The VAT percentage rate of the billing item, (from 0 - 100). + currencyRate: + type: number + format: float + description: If the currency is not in EUR, this is the conversion rate used + amount: + description: The amount for the billing item + type: integer + amountVat: + description: The VAT amount for the billing item + type: integer + amountWithVat: + description: The amount including VAT for the billing item + type: integer + createdAt: + type: string + format: datetime + description: The timestamp when the billing item was created + updatedAt: + type: string + format: datetime + description: The timestamp when the billing item was updated + required: &ref_57 + - type + - id + - title: Product Option Resource + description: A unique option for a product + type: object + additionalProperties: false + examples: *ref_45 + properties: *ref_46 + required: *ref_47 + - title: Product Variant Resource + description: Variant details for a given product. Unique products will have one single variant. + type: object + additionalProperties: false + examples: *ref_14 + properties: *ref_15 + required: *ref_16 + - title: Product Resource + description: The resource object for Product + type: object + additionalProperties: false + properties: *ref_10 + required: *ref_11 + uniqueItems: true + meta: + type: object + description: Meta with Pagination Details + required: *ref_17 + additionalProperties: true + properties: *ref_18 + links: + description: Pagination navigation links. If a link does not exist then you cannot paginate any further in that direction. + type: object + properties: *ref_19 + jsonapi: + description: An object describing the server's implementation + type: object + properties: *ref_0 + additionalProperties: false + additionalProperties: false + examples: + example: + value: + meta: + page: + from: 123e4567-e89b-12d3-a456-426614174000 + hasMore: true + perPage: 2 + to: 1ecb023e-7ec0-6d5c-a477-0242ac170008 + jsonapi: + version: '1.0' + links: + first: https://www.ankorstore.com/api/v1/orders?include=&page%5Blimit%5D=2 + next: https://www.ankorstore.com/api/v1/orders?include=&page%5Bafter%5D=797910&page%5Blimit%5D=2 + prev: https://www.ankorstore.com/api/v1/orders?include=&page%5Bbefore%5D=904234&page%5Blimit%5D=2 + data: + - type: orders + id: 123e4567-e89b-12d3-a456-426614174000 + attributes: + masterOrderId: 7ad5afec-c558-4d8f-9cc4-dac87c50c9d7 + status: invoiced + reference: 3434273911 + brandCurrency: EUR + brandNetAmount: 20596 + brandTotalAmount: 23405 + brandTotalAmountVat: 0 + brandTotalAmountWithVat: 23405 + brandRejectReason: null + retailerRejectReason: null + retailerCancellationRequestReason: null + billingName: Charles Attan + billingOrganisationName: Jumbo + billingStreet: Kortricklaan 101 + billingPostalCode: 8121 GW + billingCity: Arnhem + billingCountryCode: NL + submittedAt: '2022-03-15T10:05:09+00:00' + shippedAt: '2022-03-17T15:05:19+00:00' + brandPaidAt: null + createdAt: '2022-03-13T16:36:24+00:00' + updatedAt: '2022-03-31T11:57:13+00:00' + shippingMethod: ankorstore + relationships: + retailer: + data: + type: retailers + id: 1ecba0f4-adf0-6fbe-badf-9eb2e4c4d56c + billingItems: + data: + - type: billing-items + id: 1ece8a8c-55b9-63c6-95c3-0242ac160007 + orderItems: + data: + - type: order-items + id: 1ece8a8c-73ad-6ae4-a4ab-0242ac160007 + - type: order-items + id: 1ece8a8c-623e-6ccc-aa2e-0242ac160007 + - type: orders + id: 1ecb023e-7ec0-6d5c-a477-0242ac170007 + attributes: + masterOrderId: ef19dab7-a89e-44c7-82c2-554df38e8ba4 + status: ankor_confirmed + reference: 3434273911 + brandCurrency: EUR + brandNetAmount: 10229 + brandTotalAmount: 10940 + brandTotalAmountVat: 602 + brandTotalAmountWithVat: 11542 + brandRejectReason: null + retailerRejectReason: null + retailerCancellationRequestReason: null + billingName: Charles Attan + billingOrganisationName: Jumbo + billingStreet: Kortricklaan 101 + billingPostalCode: 8121 GW + billingCity: Arnhem + billingCountryCode: NL + submittedAt: '2022-03-17T13:19:33+00:00' + shippedAt: null + brandPaidAt: null + createdAt: '2022-02-01T14:37:10+00:00' + updatedAt: '2022-03-31T11:56:01+00:00' + shippingMethod: null + relationships: + retailer: + data: + type: retailers + id: 1ecba0f4-adf0-6fbe-badf-9eb2e4c4d56c + billingItems: + data: + - type: billing-items + id: 1ece8a8c-55b9-63c6-95c3-0242ac160007 + orderItems: + data: + - type: order-items + id: 1ece8a8c-73ad-6ae4-a4ab-0242ac160007 + '400': + description: Bad request + content: *ref_48 + '401': + description: Unauthorized + content: *ref_4 + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 + /api/v1/orders/{order}: + get: + summary: Get Internal Order + description: Retrieve a specific order + operationId: get-internal-order + tags: + - Ordering + parameters: + - name: Accept + in: header + description: application/vnd.api+json + schema: *ref_3 + - name: order + in: path + required: true + schema: &ref_58 + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + - name: include + in: query + description: '[See supported values](https://ankorstore.github.io/api-docs/#tag/Ordering/Working-with-Internal-Orders)' + allowEmptyValue: true + required: false + schema: &ref_59 + type: string + responses: + '200': + description: '[OK](https://jsonapi.org/format/#fetching-resources-responses-200)' + content: + application/vnd.api+json: + schema: + title: Order Get + type: object + additionalProperties: false + examples: &ref_60 + - jsonapi: + version: '1.0' + data: + type: order + id: 1ecb023e-7ec0-6d5c-a477-0242ac170007 + attributes: + masterOrderId: a35ec01f-d2b7-4124-a7ed-c82320c629fa + status: shipped + reference: 3434273911 + brandCurrency: EUR + brandTotalAmount: 12588 + brandTotalAmountVat: 693 + brandTotalAmountWithVat: 13281 + shippingMethod: ankorstore + shippingOverview: + availableShippingMethods: + - custom + - ankorstore + shipToAddress: + name: John Smith + organisationName: Test Retailer + street: Test Street + city: Roma + postalCode: '00222' + countryCode: IT + expectedShippingDates: + minimum: '2022-03-28T00:00:00+00:00' + maximum: '2022-03-30T23:59:59+00:00' + provider: ups + tracking: null + latestQuote: + id: 5cc76f26-0f5d-1ecb-a0d6-0242ac170009 + provider: ups + parcels: + - length: 50 + width: 100 + height: 50 + weight: 10000 + distanceUnit: cm + massUnit: g + trackedPackage: + labelUrl: https://www.ankorstore.com/api/v1/orders/1ecb023e-7ec0-6d5c-a477-0242ac170007/shipping-labels/335654/pdf + eta: null + trackingNumber: 1Z8A76E49136380279 + trackingLink: https://www.ups.com/track?tracknum=1Z8A76E49136380279&requester=WT/trackdetails + currentStatus: + status: UNKNOWN + statusDetails: null + updatedAt: '2022-03-28T15:35:19+00:00' + location: + city: null + state: null + zip: null + country: null + - length: 75 + width: 50 + height: 50 + weight: 5200 + distanceUnit: cm + massUnit: g + trackedPackage: + labelUrl: https://www.ankorstore.com/api/v1/orders/1ecb023e-7ec0-6d5c-a477-0242ac170007/shipping-labels/335655/pdf + eta: null + trackingNumber: 1Z8A76E49137225882 + trackingLink: https://www.ups.com/track?tracknum=1Z8A76E49137225882&requester=WT/trackdetails + currentStatus: + status: UNKNOWN + statusDetails: null + updatedAt: '2022-03-28T15:35:19+00:00' + location: + city: null + state: null + zip: null + country: null + transaction: + pickup: + pickupDate: '2022-03-30T00:00:00+00:00' + closeTime: '15:00:00' + readyTime: '09:00:00' + externalReferenceId: 2929602E9CP + tracking: + eta: null + trackingNumber: 1Z8A76E49136380279 + trackingLink: https://www.ups.com/track?tracknum=1Z8A76E49136380279&requester=WT/trackdetails + currentStatus: + status: UNKNOWN + statusDetails: null + updatedAt: '2022-03-28T15:35:19+00:00' + location: + city: null + state: null + zip: null + country: null + brandRejectReason: null + retailerRejectReason: null + retailerCancellationRequestReason: null + billingName: Charles Attan + billingOrganisationName: Jumbo + billingStreet: Kortricklaan 101 + billingPostalCode: 8121 GW + billingCity: Arnhem + billingCountryCode: NL + submittedAt: '2022-02-02T20:15:05.000000Z' + shippedAt: '2022-02-09T15:05:27.000000Z' + brandPaidAt: null + createdAt: '2022-02-02T19:42:31.000000Z' + updatedAt: '2022-03-11T08:57:56.000000Z' + relationships: + retailer: + data: + type: retailer + id: 092b63ce-c5b9-1eca-b05f-0242ac170007 + included: + - type: retailer + id: 092b63ce-c5b9-1eca-b05f-0242ac170007 + attributes: + companyName: null + storeName: TEST RETAILER + storeUrl: null + email: test-retailer@gmail.com + firstName: Marie-France + lastName: DESCHAMPS + taxNumber: '819470824' + vatNumber: FR58819470824 + eoriNumber: null + phoneNumberE164: '+33688615593' + businessIdentifier: '819470824' + createdAt: '2020-06-19T11:59:30.000000Z' + updatedAt: '2020-06-21T15:27:39.000000Z' + properties: &ref_61 + data: + description: The resource object for Order + type: object + additionalProperties: false + title: Order Resource + properties: *ref_40 + required: *ref_41 + included: + description: To reduce the number of HTTP requests, servers **MAY** allow responses that include related resources along with the requested primary resources. Such responses are called `compound documents`. + type: array + uniqueItems: true + items: + anyOf: + - title: Retailer Resource + type: object + additionalProperties: false + example: *ref_49 + properties: *ref_50 + required: *ref_51 + - title: Order Item Resource + type: object + additionalProperties: false + examples: *ref_52 + properties: *ref_53 + required: *ref_54 + - title: Billing Item Resource + type: object + additionalProperties: false + examples: *ref_55 + properties: *ref_56 + required: *ref_57 + - title: Product Option Resource + description: A unique option for a product + type: object + additionalProperties: false + examples: *ref_45 + properties: *ref_46 + required: *ref_47 + - title: Product Variant Resource + description: Variant details for a given product. Unique products will have one single variant. + type: object + additionalProperties: false + examples: *ref_14 + properties: *ref_15 + required: *ref_16 + - title: Product Resource + description: The resource object for Product + type: object + additionalProperties: false + properties: *ref_10 + required: *ref_11 + jsonapi: + description: An object describing the server's implementation + type: object + properties: *ref_0 + additionalProperties: false + required: &ref_62 + - data + examples: + example: + value: + jsonapi: + version: '1.0' + data: + type: order + id: 1ecb023e-7ec0-6d5c-a477-0242ac170009 + attributes: + masterOrderId: 52d7c518-b820-41af-9cc4-59dae40f2c73 + status: invoiced + reference: 3434273911 + brandCurrency: EUR + brandNetAmount: 20596 + brandTotalAmount: 23405 + brandTotalAmountVat: 0 + brandTotalAmountWithVat: 23405 + brandRejectReason: null + retailerRejectReason: null + retailerCancellationRequestReason: null + billingName: Charles Attan + billingOrganisationName: Jumbo + billingStreet: Kortricklaan 101 + billingPostalCode: 8121 GW + billingCity: Arnhem + billingCountryCode: NL + submittedAt: '2022-03-15T10:05:09+00:00' + shippedAt: '2022-03-17T15:05:19+00:00' + brandPaidAt: null + createdAt: '2022-03-13T16:36:24+00:00' + updatedAt: '2022-03-31T11:57:13+00:00' + shippingMethod: ankorstore + shippingOverview: + availableShippingMethods: + - custom + - ankorstore + shipToAddress: + name: John Smith + organisationName: TEST RETAILER + street: Test Street 14 + city: DEN HAAG + postalCode: 3333HC + countryCode: NL + expectedShippingDates: + minimum: '2022-03-18T00:00:00+00:00' + maximum: '2022-03-22T23:59:59+00:00' + provider: ups + tracking: null + latestQuote: + id: 5cc76f26-0f5d-1ecb-a0d6-0242ac170009 + provider: ups + rateAmount: + amount: 1359 + currency: EUR + rateProvider: ankorstore + shippingCostsOverview: + amount: 1037 + currency: EUR + type: fee + parcels: + - length: 30 + width: 60 + height: 40 + weight: 16500 + distanceUnit: cm + massUnit: g + trackedPackage: + labelUrl: null + eta: null + trackingNumber: 1Z8A76119134110028 + trackingLink: https://www.ups.com/track?tracknum=1Z8A76119134110028&requester=WT/trackdetails + currentStatus: + status: DELIVERED + statusDetails: Delivered + updatedAt: '2022-03-21T10:36:46+00:00' + location: + city: DEN HAAG + state: null + zip: 3333HC + country: NL + transaction: + pickup: + pickupDate: '2022-03-18T00:00:00+00:00' + closeTime: '15:00:00' + readyTime: '09:00:00' + externalReferenceId: 29QGCN35P8R + tracking: + eta: null + trackingNumber: 1Z8A76E493544110028 + trackingLink: https://www.ups.com/track?tracknum=1Z8A76E493544110028&requester=WT/trackdetails + currentStatus: + status: DELIVERED + statusDetails: Delivered + updatedAt: '2022-03-21T10:36:46+00:00' + location: + city: DEN HAAG + state: null + zip: 3333HC + country: NL + included: + - type: retailer + id: 3b656e82-0260-1ecb-9e4c-0242ac170007 + attributes: + companyName: null + storeName: TEST RETAILER + storeUrl: null + email: test_retailer@gmail.com + firstName: Test + lastName: Retailer + taxNumber: '222270824' + vatNumber: FR52222470824 + eoriNumber: null + phoneNumberE164: '+33688615666' + businessIdentifier: '819470111' + createdAt: '2020-06-19T11:59:30.000000Z' + updatedAt: '2020-06-21T15:27:39.000000Z' + '401': + description: Unauthorized + content: *ref_4 + '404': + description: '[Not found](https://jsonapi.org/format/#fetching-resources-responses-404)' + content: *ref_21 + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 + /api/v1/orders/{order}/is-fulfillable: + get: + summary: Check Internal Order Fulfillability + operationId: internal-order-is-fulfillable + description: Check whether an internal order can be fulfilled by Ankorstore logistics + tags: + - Ordering + responses: + '200': + description: No content + content: &ref_63 + application/vnd.api+json: + schema: + type: object + properties: + jsonapi: + description: An object describing the server's implementation + type: object + properties: *ref_0 + additionalProperties: false + '400': + description: Blockers that disqualify an order from fulfillment via Ankorstore logistics + content: &ref_167 + application/vnd.api+json: + schema: + type: object + properties: + jsonapi: + description: An object describing the server's implementation + type: object + properties: *ref_0 + additionalProperties: false + errors: + type: array + items: + type: object + properties: + detail: + type: string + enum: + - not_a_fulfillment_brand + - unavailable_items + - already_being_fulfilled + - not_available_for_international_orders + - stock_is_being_transferred + status: + description: The HTTP status code applicable to this problem, expressed as a string value. + type: string + title: + description: General description of the problem + type: string + meta: + type: object + additionalProperties: true + properties: + undeclaredItems: + type: array + items: + type: string + format: uuid + unavailableItems: + type: array + items: + type: string + format: uuid + '401': + description: Unauthorized + content: *ref_4 + '403': + description: '[Forbidden](https://jsonapi.org/format/#crud-creating-responses-403)' + content: *ref_20 + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 + '500': + description: '[Server Error](https://jsonapi.org/format/#errors)' + content: *ref_7 + parameters: + - schema: + type: string + in: header + name: Accept + description: application/vnd.api+json + - name: order + in: path + required: true + schema: *ref_58 + /api/v1/orders/{order}/-actions/transition: + post: + summary: Transition Internal Order + operationId: transition-internal-order + description: | + Transition an order to a new state. This endpoint can be used to accept an order (with or without modifications), + reject an order or reset generated shipping labels currently. Please see the documentation for more information. + tags: + - Ordering + parameters: + - name: Accept + in: header + description: application/vnd.api+json + schema: *ref_3 + - name: order + in: path + required: true + schema: *ref_58 + - name: include + in: query + description: '[See supported values](https://ankorstore.github.io/api-docs/#tag/Ordering/Working-with-Internal-Orders)' + allowEmptyValue: true + required: false + schema: *ref_59 + requestBody: + content: + application/vnd.api+json: + schema: + type: object + properties: + data: + oneOf: + - title: Brand Accepts Payload + type: object + required: + - type + properties: + type: + type: string + description: The transition to use + enum: + - brand-validates + attributes: + type: object + properties: + orderItems: + type: array + uniqueItems: true + description: | + To accept the order as is, leave array empty.\ + To modify a single items quantity, include it with the new quantity value.\ + To remove an order item, specify its quantity as 0.\ + Some products are sold in fixed quantities, e.g a case of 6 wine bottles. To confirm a pack of 6 bottles pass a quantity of 1. + items: + type: object + required: + - id + - type + - attributes + properties: + id: + type: string + description: Order Item Uuid + type: + type: string + enum: + - order-items + attributes: + type: object + required: + - quantity + properties: + quantity: + type: integer + description: A value of 0 indicates this order item will be removed. This value cannot go higher than the current quantity. + min: 0 + - type: object + title: Brand Rejects Payload + required: + - type + - attributes + properties: + type: + type: string + description: The transition to use + enum: + - brand-rejects + attributes: + type: object + required: + - rejectType + properties: + rejectReason: + type: string + description: A detailed description of the reason for the order rejection. Required if reject type "OTHER" is used, optional for the rest of the predefined reject types + minLength: 1 + maxLength: 1000 + writeOnly: true + rejectType: + type: string + description: One of the available reject reasons. + enum: + - BRAND_ALREADY_HAS_CUSTOMER_IN_THE_AREA + - BRAND_CANNOT_DELIVER_TO_THE_AREA + - BRAND_HAS_EXCLUSIVE_DISTRIBUTOR_IN_THE_REGION + - BUYER_NOT_A_RETAILER + - ORDER_ITEMS_PRICES_INCORRECT + - PAYMENT_ISSUES_WITH_RETAILER + - PREPARATION_TIME_TOO_HIGH + - PRODUCT_OUT_OF_STOCK + - PURCHASE_NOT_FOR_RESALE + - RETAILER_AGREED_TO_DO_CHANGES_TO_ORDER + - RETAILER_NOT_GOOD_FIT_FOR_BRAND + - RETAILER_VAT_NUMBER_MISSING + - OTHER + writeOnly: true + - type: object + title: Brand Resets Shipping Labels Generation + required: + - type + - attributes + properties: + type: + type: string + description: The transition to use + enum: + - brand-resets-shipping-labels-generation + attributes: + type: object + required: + - resetType + properties: + resetType: + type: string + description: One of the available reset reasons. + enum: + - BRAND_NEED_MORE_LABELS_TO_SHIP + - BRAND_PUT_WRONG_WEIGHT_DIMENSIONS + - BRAND_SHIPS_WITH_DIFFERENT_CARRIER + - PROBLEM_DURING_SHIPPING_LABEL_GENERATION + - RETAILER_ASKED_DELIVERY_ADDRESS_CHANGE + - SHIPPING_ADDRESS_MISMATCHES_PICKUP_ADDRESS + - OTHER + writeOnly: true + reason: + type: string + description: A detailed description of the reason for resetting the generated shipping labels. Required if reset type "OTHER" is used, optional for the rest of the predefined reset types + minLength: 1 + maxLength: 300 + writeOnly: true + - type: object + title: Brand Requests Fulfillment + required: + - type + properties: + type: + type: string + description: The transition to use + enum: + - brand-requests-fulfillment + examples: + brand-validates: + value: + data: + type: brand-validates + brand-validates-with-modifications: + value: + data: + type: brand-validates + attributes: + orderItems: + - id: 1ecb023e-8ec0-6d5c-a477-0242ac170008 + type: order-items + attributes: + quantity: 5 + brand-rejects-1: + value: + data: + type: brand-rejects + attributes: + rejectType: BRAND_ALREADY_HAS_CUSTOMER_IN_THE_AREA + brand-rejects-2: + value: + data: + type: brand-rejects + attributes: + rejectType: OTHER + rejectReason: An example reason that justifies using OTHER + brand-resets-shipping-labels-generation-using-predefined-reason: + value: + data: + type: brand-resets-shipping-labels-generation + attributes: + resetType: RETAILER_ASKED_DELIVERY_ADDRESS_CHANGE + brand-resets-shipping-labels-generation-using-custom-reason: + value: + data: + type: brand-resets-shipping-labels-generation + attributes: + resetType: OTHER + reason: An example reason that justifies using OTHER + brand-requests-fulfillment: + value: + data: + type: brand-requests-fulfillment + responses: + '200': + description: '[OK](https://jsonapi.org/format/#fetching-resources-responses-200)' + content: + application/vnd.api+json: + schema: + title: Order Get + type: object + additionalProperties: false + examples: *ref_60 + properties: *ref_61 + required: *ref_62 + examples: + brand-validates: + value: + jsonapi: + version: '1.0' + data: + type: order + id: 1ecb023e-8ec0-6d5c-a477-0242ac170007 + attributes: + status: brand_confirmed + reference: 3434273911 + brandCurrency: EUR + brandNetAmount: 10229 + brandTotalAmount: 10940 + brandTotalAmountVat: 602 + brandTotalAmountWithVat: 11542 + brandRejectReason: null + retailerRejectReason: null + retailerCancellationRequestReason: null + billingName: Charles Attan + billingOrganisationName: Jumbo + billingStreet: Kortricklaan 101 + billingPostalCode: 8121 GW + billingCity: Arnhem + billingCountryCode: NL + submittedAt: '2022-03-17T13:19:33+00:00' + shippedAt: null + brandPaidAt: null + createdAt: '2022-02-01T14:37:10+00:00' + updatedAt: '2022-03-31T15:10:07+00:00' + shippingMethod: null + shippingOverview: + availableShippingMethods: + - custom + - ankorstore + shipToAddress: + name: John Smith + organisationName: Test + street: Test Street + city: Commentry + postalCode: '03633' + countryCode: FR + expectedShippingDates: + minimum: '2022-03-22T00:00:00+00:00' + maximum: '2022-03-24T23:59:59+00:00' + provider: null + tracking: null + latestQuote: null + parcels: [] + transaction: null + brand-validates-with-modifications: + value: + jsonapi: + version: '1.0' + data: + type: order + id: 1ecb023e-8ec0-6d5c-a477-0242ac170007 + attributes: + status: brand_confirmed + reference: 3434273911 + brandCurrency: EUR + brandNetAmount: 10229 + brandTotalAmount: 10940 + brandTotalAmountVat: 602 + brandTotalAmountWithVat: 11542 + brandRejectReason: null + retailerRejectReason: null + retailerCancellationRequestReason: null + billingName: Charles Attan + billingOrganisationName: Jumbo + billingStreet: Kortricklaan 101 + billingPostalCode: 8121 GW + billingCity: Arnhem + billingCountryCode: NL + submittedAt: '2022-03-17T13:19:33+00:00' + shippedAt: null + brandPaidAt: null + createdAt: '2022-02-01T14:37:10+00:00' + updatedAt: '2022-03-31T15:10:07+00:00' + shippingMethod: null + shippingOverview: + availableShippingMethods: + - custom + - ankorstore + shipToAddress: + name: John Smith + organisationName: Test + street: Test Street + city: Commentry + postalCode: '03633' + countryCode: FR + expectedShippingDates: + minimum: '2022-03-22T00:00:00+00:00' + maximum: '2022-03-24T23:59:59+00:00' + provider: null + tracking: null + latestQuote: null + parcels: [] + transaction: null + brand-rejects: + value: + jsonapi: + version: '1.0' + data: + type: order + id: 1ecb023e-8ec0-6d5c-a477-0242ac170007 + attributes: + status: cancelled + reference: 3434273911 + brandCurrency: EUR + brandNetAmount: 10229 + brandTotalAmount: 10940 + brandTotalAmountVat: 602 + brandTotalAmountWithVat: 11542 + brandRejectReason: null + retailerRejectReason: null + retailerCancellationRequestReason: null + billingName: Charles Attan + billingOrganisationName: Jumbo + billingStreet: Kortricklaan 101 + billingPostalCode: 8121 GW + billingCity: Arnhem + billingCountryCode: NL + submittedAt: '2022-03-17T13:19:33+00:00' + shippedAt: null + brandPaidAt: null + createdAt: '2022-02-01T14:37:10+00:00' + updatedAt: '2022-03-31T15:10:07+00:00' + shippingMethod: null + shippingOverview: + availableShippingMethods: + - custom + - ankorstore + shipToAddress: + name: John Smith + organisationName: Test + street: Test Street + city: Commentry + postalCode: '03633' + countryCode: FR + expectedShippingDates: + minimum: '2022-03-22T00:00:00+00:00' + maximum: '2022-03-24T23:59:59+00:00' + provider: null + tracking: null + latestQuote: null + parcels: [] + transaction: null + '401': + description: Unauthorized + content: *ref_4 + '403': + description: '[Forbidden](https://jsonapi.org/format/#crud-creating-responses-403)' + content: *ref_20 + '404': + description: '[Not found](https://jsonapi.org/format/#fetching-resources-responses-404)' + content: *ref_21 + '406': + description: Not Acceptable + content: *ref_5 + '409': + description: Conflict + content: + application/vnd.api+json: + schema: + type: object + additionalProperties: false + properties: *ref_1 + required: *ref_2 + example: + jsonapi: + version: '1.0' + errors: + - code: ORDER_ACTION_TRANSITION_FAILED + detail: Order cannot be transitioned using brand-validates from this state + status: '409' + '415': + description: Unsupported Media Type + content: *ref_6 + /api/v1/external-orders/non-ankorstore-fulfillment-orders: + post: + summary: Create NAFO External Order + operationId: ordering-create-non-ankorstore-fulfillment-order + description: Creates a new External Order of type `nafo` + tags: + - Ordering + parameters: + - name: Accept + in: header + description: application/vnd.api+json + schema: *ref_3 + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + shippingAddress: + description: Shipping address of the recipient. + type: object + properties: + country: + type: string + description: ISO 3166-1 country code. + pattern: ^[A-Z]{2}$ + postalCode: + type: string + description: Valid postal code, matching the country. + city: + type: string + minLength: 1 + maxLength: 255 + description: Name of the destination city. + street: + type: string + minLength: 1 + maxLength: 60 + description: | + Street address, should not exceed the maximum length + in order to fit the dedicated place on the shipping label. + company: + type: string + maxLength: 70 + description: Name of the company + firstName: + type: string + minLength: 1 + maxLength: 64 + description: First name of the person, receiving the order + lastName: + type: string + minLength: 1 + maxLength: 64 + description: Last name of the person, receiving the order + phone: + type: string + minLength: 1 + description: Phone number of the person, receiving the order. The format match the country. + email: + type: string + format: email + description: Email of the person, receiving the order + required: + - country + - postalCode + - city + - street + - company + - firstName + - lastName + - phone + - email + items: + type: array + description: List of fulfillable items with their corresponding quantities. + items: + type: object + properties: + fulfillableId: + type: string + format: uuid + description: Fulfillable identifier, find more about it [here](#tag/Fulfillment/About-Fulfillment). + quantity: + type: integer + description: Quantity of the fulfillable item in units. + required: + - fulfillableId + - quantity + masterOrderUuid: + type: string + format: uuid + description: | + Pre-generated UUID for the order being created. Despite this UUID is optional and being omitted, + will be generated by the system, having it in advance will make it easier to identify and track the + status of the created order (considering the asynchronous nature of the process). + customReference: + type: string + description: | + Optional brand-defined custom reference to add to the created order. + Usually represents some order identifier in the brand's order management system, used outside of Ankorstore. + recipientType: + description: The type of recipient for this order + type: string + enum: + - business + - consumer + default: business + required: + - shippingAddress + - items + responses: + '200': + description: No content + content: *ref_63 + '400': + description: Bad request + content: *ref_48 + '401': + description: Unauthorized + content: *ref_4 + '403': + description: '[Forbidden](https://jsonapi.org/format/#crud-creating-responses-403)' + content: *ref_20 + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 + '422': + description: 'Unprocessable Entity : Data provided are invalid' + content: *ref_64 + '500': + description: '[Server Error](https://jsonapi.org/format/#errors)' + content: *ref_7 + /api/v1/orders/{order}/accept: + post: + summary: '[Ordering] Accept Order' + deprecated: true + tags: + - Deprecated + operationId: brand-accept-order + description: '[Deprecated] Please use the Order Transition endpoint.' + parameters: + - name: Accept + in: header + description: application/vnd.api+json + schema: *ref_3 + - name: order + in: path + required: true + schema: *ref_58 + - name: include + in: query + description: '[See supported values](https://ankorstore.github.io/api-docs/#tag/Ordering/Working-with-Internal-Orders)' + allowEmptyValue: true + required: false + schema: *ref_59 + responses: + '200': + description: '[OK](https://jsonapi.org/format/#fetching-resources-responses-200)' + content: + application/vnd.api+json: + schema: + title: Order Get + type: object + additionalProperties: false + examples: *ref_60 + properties: *ref_61 + required: *ref_62 + examples: + example: + value: + jsonapi: + version: '1.0' + data: + type: order + id: 1ecb023e-8ec0-6d5c-a477-0242ac170007 + attributes: + status: brand_confirmed + reference: 3434273911 + brandCurrency: EUR + brandNetAmount: 10229 + brandTotalAmount: 10940 + brandTotalAmountVat: 602 + brandTotalAmountWithVat: 11542 + brandRejectReason: null + retailerRejectReason: null + retailerCancellationRequestReason: null + billingName: Charles Attan + billingOrganisationName: Jumbo + billingStreet: Kortricklaan 101 + billingPostalCode: 8121 GW + billingCity: Arnhem + billingCountryCode: NL + submittedAt: '2022-03-17T13:19:33+00:00' + shippedAt: null + brandPaidAt: null + createdAt: '2022-02-01T14:37:10+00:00' + updatedAt: '2022-03-31T15:10:07+00:00' + shippingMethod: null + shippingOverview: + availableShippingMethods: + - custom + - ankorstore + shipToAddress: + name: John Smith + organisationName: Test + street: Test Street + city: Commentry + postalCode: '03633' + countryCode: FR + expectedShippingDates: + minimum: '2022-03-22T00:00:00+00:00' + maximum: '2022-03-24T23:59:59+00:00' + provider: null + tracking: null + latestQuote: null + parcels: [] + transaction: null + '401': + description: Unauthorized + content: *ref_4 + '403': + description: '[Forbidden](https://jsonapi.org/format/#crud-creating-responses-403)' + content: *ref_20 + '404': + description: '[Not found](https://jsonapi.org/format/#fetching-resources-responses-404)' + content: *ref_21 + '406': + description: Not Acceptable + content: *ref_5 + '409': + description: Conflict + content: + application/vnd.api+json: + schema: + type: object + additionalProperties: false + properties: *ref_1 + required: *ref_2 + example: + errors: + - code: ORDER_ACTION_ACCEPT_FAILED + detail: Order cannot be accepted from this state + status: '409' + '415': + description: Unsupported Media Type + content: *ref_6 + /api/v1/orders/{order}/reject: + post: + summary: '[Ordering] Reject Order' + deprecated: true + tags: + - Deprecated + operationId: brand-reject-order + description: '[Deprecated] Please use the Order Transition endpoint.' + parameters: + - name: Accept + in: header + description: application/vnd.api+json + schema: *ref_3 + - name: order + in: path + required: true + schema: *ref_58 + - name: include + in: query + description: '[See supported values](https://ankorstore.github.io/api-docs/#tag/Ordering/Working-with-Internal-Orders)' + allowEmptyValue: true + required: false + schema: *ref_59 + responses: + '200': + description: '[OK](https://jsonapi.org/format/#fetching-resources-responses-200)' + content: + application/vnd.api+json: + schema: + title: Order Get + type: object + additionalProperties: false + examples: *ref_60 + properties: *ref_61 + required: *ref_62 + examples: + example: + value: + jsonapi: + version: '1.0' + data: + type: order + id: 1ecb023e-7ec0-6d5c-a477-0242ac170007 + attributes: + status: rejected + reference: 3434273911 + brandCurrency: EUR + brandNetAmount: 10229 + brandTotalAmount: 10940 + brandTotalAmountVat: 602 + brandTotalAmountWithVat: 11542 + brandRejectReason: Products not in stock. + retailerRejectReason: null + retailerCancellationRequestReason: null + billingName: Charles Attan + billingOrganisationName: Jumbo + billingStreet: Kortricklaan 101 + billingPostalCode: 8121 GW + billingCity: Arnhem + billingCountryCode: NL + submittedAt: '2022-03-17T13:19:33+00:00' + shippedAt: null + brandPaidAt: null + createdAt: '2022-02-01T14:37:10+00:00' + updatedAt: '2022-03-31T15:10:07+00:00' + shippingMethod: null + shippingOverview: + availableShippingMethods: + - custom + - ankorstore + shipToAddress: + name: John Smith + organisationName: Test + street: Test Street + city: Commentry + postalCode: '03633' + countryCode: FR + expectedShippingDates: + minimum: '2022-03-22T00:00:00+00:00' + maximum: '2022-03-24T23:59:59+00:00' + provider: null + tracking: null + latestQuote: null + parcels: [] + transaction: null + '401': + description: Unauthorized + content: *ref_4 + '403': + description: '[Forbidden](https://jsonapi.org/format/#crud-creating-responses-403)' + content: *ref_20 + '404': + description: '[Not found](https://jsonapi.org/format/#fetching-resources-responses-404)' + content: *ref_21 + '406': + description: Not Acceptable + content: *ref_5 + '409': + description: Conflict + content: + application/vnd.api+json: + schema: + type: object + additionalProperties: false + properties: *ref_1 + required: *ref_2 + examples: + State update failed: + value: + jsonapi: + version: '1.0' + errors: + - code: ORDER_ACTION_REJECT_FAILED + detail: Order cannot be rejected from this state + status: '409' + '415': + description: Unsupported Media Type + content: *ref_6 + '422': + description: 'Unprocessable Entity : Data provided are invalid' + content: + application/vnd.api+json: + schema: + type: object + additionalProperties: false + properties: *ref_1 + required: *ref_2 + example: + jsonapi: + version: string + errors: + - detail: The order.reject reason is required. + source: + pointer: order.rejectReason + status: '422' + title: Unprocessable Content + requestBody: + content: + application/vnd.api+json: + schema: + description: Reject payload + type: object + properties: + order: + type: object + required: + - rejectType + properties: + rejectReason: + type: string + description: A detailed description of the reason for the order rejection. Required if reject type "OTHER" is used, optional for the rest of the predefined reject types + minLength: 1 + maxLength: 1000 + writeOnly: true + rejectType: + type: string + description: One of the available reject reasons. If this field is omitted from the payload it will default to OTHER to ensure backwards compatibility. Please note that this field will be mandatory in the future. + enum: + - BRAND_ALREADY_HAS_CUSTOMER_IN_THE_AREA + - BRAND_CANNOT_DELIVER_TO_THE_AREA + - BRAND_HAS_EXCLUSIVE_DISTRIBUTOR_IN_THE_REGION + - BUYER_NOT_A_RETAILER + - ORDER_ITEMS_PRICES_INCORRECT + - PAYMENT_ISSUES_WITH_RETAILER + - PREPARATION_TIME_TOO_HIGH + - PRODUCT_OUT_OF_STOCK + - PURCHASE_NOT_FOR_RESALE + - RETAILER_AGREED_TO_DO_CHANGES_TO_ORDER + - RETAILER_NOT_GOOD_FIT_FOR_BRAND + - RETAILER_VAT_NUMBER_MISSING + - OTHER + writeOnly: true + required: + - order + examples: + predefined-reject-type: + value: + order: + rejectType: PRODUCT_OUT_OF_STOCK + custom-reject-reason: + value: + order: + rejectType: OTHER + rejectReason: Unfortunately these days we cannot send the order due to lack of the necessary package materials + /api/v1/orders/{order}/shipping-quotes: + post: + summary: List Shipping Quotes + operationId: list-order-shipping-quotes + description: | + List multiple carrier service quotes that you can choose to ship your order. + Please visit our [FAQs](https://knowledgecommunity.force.com/faq/s/article/how-do-i-benefit-from-shipping-with-ankorstore?language=en_US) for more information.' + tags: + - Shipping + parameters: + - name: Accept + in: header + description: application/vnd.api+json + schema: *ref_3 + - name: order + in: path + required: true + schema: &ref_65 + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + requestBody: + content: + application/vnd.api+json: + schema: + properties: + parcels: + type: array + minimum: 1 + maximum: 20 + items: + type: object + required: + - kg + - height + - length + - width + properties: + kg: + type: number + description: The weight of the parcel in kilograms + min: 0.001 + maximum: 30 + height: + type: number + description: The height of the parcel in centimeters + min: 1 + maximum: 274 + length: + type: number + description: The length of the parcel in centimeters + min: 1 + maximum: 274 + width: + type: number + description: The width of the parcel in centimeters + min: 1 + maximum: 274 + required: + - parcels + example: + parcels: + - length: 20 + width: 20 + height: 20 + kg: 21 + responses: + '200': + description: A list of shipping quotes + content: + application/vnd.api+json: + schema: + type: object + required: &ref_132 + - data + properties: &ref_133 + data: + type: array + items: + type: object + description: Quote resource + properties: + quoteUuid: + type: string + description: The unique identifier for the quote as an uuid + carrierCode: + type: string + description: The carrier code for the quote + serviceCode: + type: string + description: The service code for the quote + serviceCommercialName: + type: string + description: The commercial name of the service + collectionMethod: + description: The collection method for the quote + type: array + items: + type: string + enum: + - pickup + - drop-off + shippingCost: + type: object + properties: + amount: + type: number + description: The amount of the shipping cost + currency: + type: string + description: The currency of the shipping cost + timeInTransit: + type: + - 'null' + - object + description: Delivery estimation information if provided by carrier + properties: + estimatedDeliveryDate: + type: + - 'null' + - string + format: date + description: Estimation of delivery date by the carrier + pickupDate: + type: + - 'null' + - string + format: date + description: Pickup date considered for the estimation + businessDaysInTransit: + type: + - 'null' + - number + description: Number of business days the shipment is in transit + jsonapi: + description: An object describing the server's implementation + type: object + properties: *ref_0 + additionalProperties: false + examples: + example: + value: + jsonapi: + version: '1.0' + data: + - quoteUuid: 1eda3cbb-983b-6a4a-b395-6a0440190584 + carrierCode: ups + serviceCode: '11' + serviceCommercialName: UPS STANDARD + collectionMethod: + - pickup + shippingCost: + amount: 12 + currency: EUR + timeInTransit: + estimatedDeliveryDate: '2024-09-09' + pickupDate: '2024-09-07' + businessDaysInTransit: 2 + '404': + description: '[Not found](https://jsonapi.org/format/#fetching-resources-responses-404)' + content: *ref_21 + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 + '422': + description: 'Unprocessable Entity : Data provided are invalid' + content: + application/vnd.api+json: + schema: + type: object + additionalProperties: false + properties: *ref_1 + required: *ref_2 + examples: + example: + value: + jsonapi: + version: string + errors: + - detail: The field is required. + source: + pointer: field + status: '422' + title: Unprocessable Content + - detail: The package dimensions are too big. Packages can be up to 400 cm in length and girth combined + source: + pointer: shipping.parcels.0 + status: '422' + title: Unprocessable Content + - detail: The parcel weight (kg) must be between 0.001 and 30.000. + source: + pointer: shipping.parcels.0.kg + status: '422' + title: Unprocessable Content + - detail: The parcel length may not be greater than 274. + source: + pointer: shipping.parcels.0.length + status: '422' + title: Unprocessable Content + - detail: The parcel width may not be greater than 274. + source: + pointer: shipping.parcels.0.width + status: '422' + title: Unprocessable Content + - detail: The parcel height may not be greater than 274. + source: + pointer: shipping.parcels.0.height + status: '422' + title: Unprocessable Content + /api/v1/shipping-quotes/{quote}/confirm: + post: + summary: Confirm Shipping Quote + operationId: confirm-order-shipping-quote + description: | + Use this endpoint to confirm which quote you want to use to ship your order. + You can confirm either custom or ankorstore quote. + tags: + - Shipping + parameters: + - name: Accept + in: header + description: application/vnd.api+json + schema: *ref_3 + - name: quote + in: path + required: true + schema: &ref_159 + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + requestBody: + content: + application/vnd.api+json: + schema: + type: object + properties: + labelFormat: + type: string + description: This field is not required. If you don't' define it we will use the default label format as well. + enum: + - full_page + - default + default: default + tracking: + oneOf: + - type: object + description: Tracking Provider + Number for custom quote + required: + - trackingProvider + - trackingNumber + properties: + trackingProvider: + type: string + description: Tracking provider is required with trackingNumber if your define an tracking key in your payload. You can define trackingLink instead of define trackingProvider & trackingNumber + trackingNumber: + description: The tracking number (may contain characters as well) + type: string + - type: object + description: Tracking Link + required: + - trackingLink + properties: + trackingLink: + type: string + format: url + description: Tracking link is required if your define an tracking key in your payload. You can define trackingProvider & trackingNumber instead + examples: + example-with-full-page-label-format: + value: + labelFormat: default + example-with-provider-and-number: + value: + tracking: + trackingProvider: ups + trackingNumber: '123456' + example-with-link: + value: + tracking: + trackingLink: https://www.dhl.com/fr-en/home/tracking/tracking-parcel.html?submit=1&tracking-id=1Z8A76E46801183396 + responses: + '200': + description: Successful response + content: + application/vnd.api+json: + schema: + type: object + properties: &ref_134 + data: + type: object + properties: + id: + type: string + uuid: + type: string + orderUuid: + type: string + provider: + type: string + currency: + type: string + shippingCost: + type: string + description: Shipping cost subtracted from total amount for ankorstore quote - Available only for ankorstore quote + refund: + type: string + description: Refund done to the brand for custom quote - Available only for custom quote + jsonapi: + description: An object describing the server's implementation + type: object + properties: *ref_0 + additionalProperties: false + examples: + example-with-shipping-cost: + value: + jsonapi: + version: '1.0' + data: + id: '991836' + uuid: 1eda3cbb-983b-6a4a-b395-6a0440190584 + orderUuid: 1ed9f5cc-ce42-625a-a8f1-b6ea0809b6f7 + provider: ups + currency: EUR + shippingCost: €12.00 + example-with-refund: + value: + jsonapi: + version: '1.0' + data: + id: '991836' + uuid: 1eda3cbb-983b-6a4a-b395-6a0440190584 + orderUuid: 1ed9f5cc-ce42-625a-a8f1-b6ea0809b6f7 + provider: ups + currency: EUR + refund: €12.00 + '401': + description: Unauthorized + content: *ref_4 + '403': + description: '[Forbidden](https://jsonapi.org/format/#crud-creating-responses-403)' + content: *ref_20 + '404': + description: '[Not found](https://jsonapi.org/format/#fetching-resources-responses-404)' + content: *ref_21 + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 + '422': + description: 'Unprocessable Entity : Data provided are invalid' + content: *ref_64 + /api/v1/orders/{order}/ship/schedule-pickup: + post: + summary: Schedule Pickup for order + operationId: ship-internal-order-schedule-pickup + description: Use this endpoint for scheduling a pickup for the order + tags: + - Shipping + parameters: + - name: Accept + in: header + description: application/vnd.api+json + schema: *ref_3 + - name: order + in: path + required: true + schema: *ref_65 + responses: + '200': + description: Order Resource + content: + application/vnd.api+json: + schema: + title: Order Get + type: object + additionalProperties: false + examples: *ref_60 + properties: *ref_61 + required: *ref_62 + '403': + description: '[Forbidden](https://jsonapi.org/format/#crud-creating-responses-403)' + content: *ref_20 + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 + '422': + description: 'Unprocessable Entity : Data provided are invalid' + content: *ref_64 + '500': + description: Internal Server Error + content: + application/vnd.api+json: + schema: + type: object + additionalProperties: false + properties: *ref_1 + required: *ref_2 + example: + jsonapi: + version: string + errors: + - code: INTERNAL_ERROR + detail: 'Cannot ship the order: {...}' + status: '500' + requestBody: + content: + application/vnd.api+json: + schema: + type: object + properties: + order: + oneOf: + - type: object + description: Tracking Provider + Number + required: + - pickupDate + - pickupTime + - pickupAddress + properties: + pickupDate: + type: string + description: Requested date for the pickup + pickupTime: + description: Time period for the pickup (9-15 or 11-17) + type: string + pickupAddress: + description: Address for the pickup + type: object + examples: + example: + value: + pickupDate: 07-04-2022 + pickupTime: 9-15 + pickupAddress: + name: John Doe + contactName: John Doe + countryCode: FR + city: Rennes + postalCode: '35000' + street: 1 rue des lilas + phoneNumber: '+33700000000' + /api/v1/orders/{order}/ship/custom: + post: + summary: Ship Order With Custom + operationId: ship-internal-order-custom + description: Ship Internal Order using the brands own method + tags: + - Shipping + parameters: + - name: Accept + in: header + description: application/vnd.api+json + schema: *ref_3 + - name: order + in: path + required: true + schema: *ref_65 + responses: + '200': + description: Order Resource + content: + application/vnd.api+json: + schema: + title: Order Get + type: object + additionalProperties: false + examples: *ref_60 + properties: *ref_61 + required: *ref_62 + examples: + example: + value: + jsonapi: + version: '1.0' + data: + type: order + id: 1ecb023e-7ec0-6d5c-a477-0242ac170007 + attributes: + status: brand_confirmed + reference: 3434273911 + brandCurrency: EUR + brandNetAmount: 10229 + brandTotalAmount: 10940 + brandTotalAmountVat: 602 + brandTotalAmountWithVat: 11542 + brandRejectReason: null + retailerRejectReason: null + retailerCancellationRequestReason: null + billingName: Charles Attan + billingOrganisationName: Jumbo + billingStreet: Kortricklaan 101 + billingPostalCode: 8121 GW + billingCity: Arnhem + billingCountryCode: NL + submittedAt: '2022-03-17T13:19:33+00:00' + shippedAt: null + brandPaidAt: null + createdAt: '2022-02-01T14:37:10+00:00' + updatedAt: '2022-03-31T15:10:07+00:00' + shippingMethod: custom + shippingOverview: + availableShippingMethods: + - custom + - ankorstore + shipToAddress: + name: John Smith + organisationName: Test + street: Test Street + city: Commentry + postalCode: '03633' + countryCode: FR + expectedShippingDates: + minimum: '2022-03-22T00:00:00+00:00' + maximum: '2022-03-24T23:59:59+00:00' + provider: null + tracking: null + latestQuote: + id: 5cc76f26-0f5d-1ecb-a0d6-0242ac170009 + provider: custom + rateAmount: + amount: 1359 + currency: EUR + rateProvider: ankorstore + shippingCostsOverview: + amount: 1037 + currency: EUR + type: refund + parcels: + - length: 30 + width: 60 + height: 40 + weight: 16500 + distanceUnit: cm + massUnit: g + trackedPackage: null + - length: 30 + width: 60 + height: 40 + weight: 20000 + distanceUnit: cm + massUnit: g + trackedPackage: null + transaction: null + '401': + description: Unauthorized + content: *ref_4 + '403': + description: '[Forbidden](https://jsonapi.org/format/#crud-creating-responses-403)' + content: *ref_20 + '404': + description: '[Not found](https://jsonapi.org/format/#fetching-resources-responses-404)' + content: *ref_21 + '406': + description: Not Acceptable + content: *ref_5 + '409': + description: Conflict + content: + application/vnd.api+json: + schema: + type: object + additionalProperties: false + properties: *ref_1 + required: *ref_2 + example: + jsonapi: + version: '1.0' + errors: + - code: STATE_UPDATE_FAILED + detail: Order cannot be shipped from this state + status: '409' + '415': + description: Unsupported Media Type + content: *ref_6 + '422': + description: 'Unprocessable Entity : Data provided are invalid' + content: *ref_64 + requestBody: + content: + application/vnd.api+json: + schema: + type: object + properties: + shipping: + type: object + properties: + parcels: + type: array + uniqueItems: true + minItems: 1 + items: + description: Shipping Label Parcel. Packages can be up to 400 cm in length and girth combined + type: object + properties: &ref_68 + length: + type: integer + maximum: 274 + width: + type: integer + maximum: 274 + height: + type: integer + maximum: 274 + distanceUnit: + type: string + description: The unit of distance + enum: *ref_66 + weight: + type: integer + minimum: 1 + maximum: 30000 + massUnit: + type: string + description: The unit of mass + enum: *ref_67 + required: &ref_69 + - length + - width + - height + - distanceUnit + - weight + - massUnit + required: + - parcels + required: + - shipping + examples: + example: + value: + shipping: + parcels: + - length: 100 + width: 10 + height: 10 + distanceUnit: cm + weight: 2000 + massUnit: g + - length: 120 + width: 20 + height: 20 + distanceUnit: cm + weight: 2000 + massUnit: g + /api/v1/orders/{order}/ship/ankorstore: + post: + summary: '[Shipping] Ship Order with Ankorstore' + description: '[Deprecated] This endpoint is deprecated. We encourage you to use the List Order Quotes endpoint instead.' + deprecated: true + operationId: ship-internal-order-ankorstore + tags: + - Deprecated + parameters: + - name: Accept + in: header + description: application/vnd.api+json + schema: *ref_3 + - name: order + in: path + required: true + schema: *ref_65 + requestBody: + content: + application/vnd.api+json: + schema: + type: object + properties: + shipping: + type: object + required: + - parcels + properties: + parcels: + type: array + uniqueItems: true + minItems: 1 + items: + description: Shipping Label Parcel. Packages can be up to 400 cm in length and girth combined + type: object + properties: *ref_68 + required: *ref_69 + required: + - shipping + examples: + example: + value: + shipping: + parcels: + - length: 100 + width: 10 + height: 10 + distanceUnit: cm + weight: 2000 + massUnit: g + responses: + '200': + description: Order Resource + content: + application/vnd.api+json: + schema: + title: Order Get + type: object + additionalProperties: false + examples: *ref_60 + properties: *ref_61 + required: *ref_62 + examples: + example: + value: + jsonapi: + version: '1.0' + data: + type: order + id: 1ecb023e-7ec0-6d5c-a477-0242ac170007 + attributes: + status: brand_confirmed + reference: 3434273911 + brandCurrency: EUR + brandNetAmount: 10229 + brandTotalAmount: 10940 + brandTotalAmountVat: 602 + brandTotalAmountWithVat: 11542 + brandRejectReason: null + retailerRejectReason: null + retailerCancellationRequestReason: null + billingName: Charles Attan + billingOrganisationName: Jumbo + billingStreet: Kortricklaan 101 + billingPostalCode: 8121 GW + billingCity: Arnhem + billingCountryCode: NL + submittedAt: '2022-03-17T13:19:33+00:00' + shippedAt: null + brandPaidAt: null + createdAt: '2022-02-01T14:37:10+00:00' + updatedAt: '2022-03-31T15:10:07+00:00' + shippingMethod: ankorstore + shippingOverview: + availableShippingMethods: + - custom + - ankorstore + shipToAddress: + name: John Smith + organisationName: Test + street: Test Street + city: Commentry + postalCode: '03633' + countryCode: FR + expectedShippingDates: + minimum: '2022-03-22T00:00:00+00:00' + maximum: '2022-03-24T23:59:59+00:00' + provider: null + tracking: null + latestQuote: + id: 5cc76f26-0f5d-1ecb-a0d6-0242ac170009 + provider: ups + rateAmount: + amount: 1359 + currency: EUR + rateProvider: ankorstore + shippingCostsOverview: + amount: 1037 + currency: EUR + type: fee + parcels: + - length: 30 + width: 60 + height: 40 + weight: 16500 + distanceUnit: cm + massUnit: g + trackedPackage: null + - length: 30 + width: 60 + height: 40 + weight: 20000 + distanceUnit: cm + massUnit: g + trackedPackage: null + transaction: null + '401': + description: Unauthorized + content: *ref_4 + '403': + description: '[Forbidden](https://jsonapi.org/format/#crud-creating-responses-403)' + content: *ref_20 + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 + '422': + description: 'Unprocessable Entity : Data provided are invalid' + content: + application/vnd.api+json: + schema: + type: object + additionalProperties: false + properties: *ref_1 + required: *ref_2 + examples: + example: + value: + jsonapi: + version: string + errors: + - detail: The field is required. + source: + pointer: field + status: '422' + title: Unprocessable Content + - detail: The shipping.parcels.0.weight may not be greater than 30000. + source: + pointer: shipping.parcels.0.weight + status: '422' + title: Unprocessable Content + - detail: The package dimensions are too big. Length (longest measurement) can be up to 274 cm + source: + pointer: shipping.parcels.1 + status: '422' + title: Unprocessable Content + - detail: The package dimensions are too big. Packages can be up to 400 cm in length and girth combined + source: + pointer: shipping.parcels.2 + status: '422' + title: Unprocessable Content + /api/v1/orders/{order}/ship/confirm: + post: + summary: '[Shipping] Confirm Order Shipping' + deprecated: true + operationId: confirm-order-shipping + description: '[Deprecated] Please use the [Confirm Shipping Quote endpoint](#tag/Shipping/operations/confirm-shipping-quote).' + tags: + - Deprecated + parameters: + - name: Accept + in: header + description: application/vnd.api+json + schema: *ref_3 + - name: order + in: path + required: true + schema: *ref_65 + responses: + '200': + description: Order Resource + content: + application/vnd.api+json: + schema: + title: Order Get + type: object + additionalProperties: false + examples: *ref_60 + properties: *ref_61 + required: *ref_62 + examples: + example: + value: + jsonapi: + version: '1.0' + data: + type: order + id: 1ecb023e-7ec0-6d5c-a477-0242ac170007 + attributes: + status: brand_confirmed + reference: 3434273911 + brandCurrency: EUR + brandNetAmount: 10229 + brandTotalAmount: 10940 + brandTotalAmountVat: 602 + brandTotalAmountWithVat: 11542 + brandRejectReason: null + retailerRejectReason: null + retailerCancellationRequestReason: null + billingName: Charles Attan + billingOrganisationName: Jumbo + billingStreet: Kortricklaan 101 + billingPostalCode: 8121 GW + billingCity: Arnhem + billingCountryCode: NL + submittedAt: '2022-03-17T13:19:33+00:00' + shippedAt: null + brandPaidAt: null + createdAt: '2022-02-01T14:37:10+00:00' + updatedAt: '2022-03-31T15:10:07+00:00' + shippingMethod: custom + shippingOverview: + availableShippingMethods: + - custom + - ankorstore + shipToAddress: + name: John Smith + organisationName: Test + street: Test Street + city: Commentry + postalCode: '03633' + countryCode: FR + expectedShippingDates: + minimum: '2022-03-22T00:00:00+00:00' + maximum: '2022-03-24T23:59:59+00:00' + provider: ups + tracking: + number: '12345' + link: https://www.ups.com/track?tracknum=123456&requester=WT/trackdetails + latestQuote: + id: 5cc76f26-0f5d-1ecb-a0d6-0242ac170009 + provider: custom + rateAmount: + amount: 1359 + currency: EUR + rateProvider: ankorstore + shippingCostsOverview: + amount: 1037 + currency: EUR + type: refund + parcels: + - length: 30 + width: 60 + height: 40 + weight: 16500 + distanceUnit: cm + massUnit: g + trackedPackage: null + - length: 30 + width: 60 + height: 40 + weight: 20000 + distanceUnit: cm + massUnit: g + trackedPackage: null + transaction: null + '401': + description: Unauthorized + content: *ref_4 + '403': + description: '[Forbidden](https://jsonapi.org/format/#crud-creating-responses-403)' + content: *ref_20 + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 + '422': + description: 'Unprocessable Entity : Data provided are invalid' + content: *ref_64 + requestBody: + content: + application/vnd.api+json: + schema: + type: object + properties: + order: + oneOf: + - type: object + description: Tracking Provider + Number + required: + - trackingProvider + - trackingNumber + properties: + trackingProvider: + type: string + description: Tracking provider is required with trackingNumber if your define an order key in your payload. You can define trackingLink instead of define trackingProvider & trackingNumber + trackingNumber: + description: The tracking number (may contain characters as well) + type: string + - type: object + description: Tracking Link + required: + - trackingLink + properties: + trackingLink: + type: string + format: url + description: Tracking link is required if your define an order key in your payload + examples: + example-with-provider-and-number: + value: + order: + trackingProvider: ups + trackingNumber: '123456' + example-with-link: + value: + order: + trackingLink: https://www.dhl.com/fr-en/home/tracking/tracking-parcel.html?submit=1&tracking-id=1Z8A76E46801183396 + /api/v1/fulfillment/orders/{id}: + get: + summary: Get Fulfillment Order + operationId: fulfillment-get-order + description: Returns details of a single fulfillment order + tags: + - Fulfillment + parameters: + - name: Accept + in: header + description: application/vnd.api+json + schema: *ref_3 + - schema: + type: string + format: uuid + name: id + in: path + required: true + description: Fulfillment order ID + - schema: + type: string + enum: + - statusUpdates + name: include + in: query + description: 'A comma-separated list of resources to include (e.g: statusUpdates)' + responses: + '200': + description: Single fulfillment order + content: &ref_168 + application/vnd.api+json: + schema: + type: object + properties: + data: + properties: *ref_70 + required: *ref_71 + jsonapi: + description: An object describing the server's implementation + type: object + properties: *ref_0 + additionalProperties: false + included: + type: array + items: + anyOf: + - properties: *ref_72 + required: + - data + - jsonapi + '401': + description: Unauthorized + content: *ref_4 + '403': + description: '[Forbidden](https://jsonapi.org/format/#crud-creating-responses-403)' + content: *ref_20 + '404': + description: '[Not found](https://jsonapi.org/format/#fetching-resources-responses-404)' + content: *ref_21 + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 + '500': + description: '[Server Error](https://jsonapi.org/format/#errors)' + content: *ref_7 + /api/v1/fulfillment/fulfillable: + get: + summary: List Fulfillables + operationId: fulfillment-list-fulfillable + description: Returns a list of fulfillables with their stock availability + tags: + - Fulfillment + responses: + '200': + description: Set of fulfillment fullfilables + content: &ref_169 + application/vnd.api+json: + schema: + type: object + properties: + data: + type: array + items: + properties: &ref_137 + type: + type: string + description: '[resource object type](https://jsonapi.org/format/#document-resource-object-identification)' + id: + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + attributes: + description: A fulfillable entity, which can be either an item or a bundle (set of items) + type: object + properties: &ref_135 + fulfillableId: + type: string + format: uuid + batchQuantity: + description: quantity in batches + type: integer + unitQuantity: + description: quantity in units + type: integer + required: &ref_136 + - fulfillableId + - batchQuantity + - unitQuantity + relationships: + type: object + properties: + item: + type: object + properties: + data: + anyOf: + - description: Resource identification present in Resource Objects and Resource Identifier Objects. + type: object + required: *ref_12 + properties: *ref_13 + additionalProperties: false + - type: 'null' + lots: + type: object + properties: + data: + anyOf: + - description: An array of objects each containing `type` and `id` members for to-many relationships. + type: array + items: *ref_9 + uniqueItems: true + - type: 'null' + required: &ref_138 + - type + - id + - attributes + jsonapi: + description: An object describing the server's implementation + type: object + properties: *ref_0 + additionalProperties: false + included: + type: array + items: + anyOf: + - properties: &ref_73 + type: + type: string + description: '[resource object type](https://jsonapi.org/format/#document-resource-object-identification)' + id: + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + attributes: + type: object + properties: &ref_139 + fulfillmentItemId: + type: string + format: uuid + availableQuantity: + type: integer + expiryDate: + description: Optional expiry date of the lot + type: + - string + - 'null' + format: date-time + sellByDate: + description: If the lot can expire, last point in time when this lot can be used to fulfill an order + type: + - string + - 'null' + format: date-time + lotNumber: + type: string + required: &ref_140 + - fulfillmentItemId + - availableQuantity + - lotNumber + relationships: + type: object + required: &ref_74 + - type + - id + - attributes + - properties: &ref_144 + type: + type: string + description: '[resource object type](https://jsonapi.org/format/#document-resource-object-identification)' + id: + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + attributes: + allOf: &ref_143 + - title: FulfillmentItem + type: object + properties: &ref_141 + productVariantId: + type: string + format: uuid + barcode: + type: string + pattern: ^\d{13,14}$ + unitsPerBatch: + type: integer + unitCostMargin: + type: number + format: float + deprecated: true + unitCost: + type: number + format: float + sku: + type: string + productName: + type: string + categoryName: + type: string + classificationCode: + type: string + expiryTracked: + type: boolean + default: false + shelfLife: + type: + - integer + - 'null' + lotTracked: + type: boolean + default: false + isFragile: + description: Whether the item is considered fragile + type: boolean + default: false + isOrganic: + description: Whether the item is considered organic + type: boolean + default: false + needRepack: + description: Whether the item needs to be repacked before shipping + type: boolean + default: false + needRelabel: + description: Whether the item needs to be relabeled before shipping + type: boolean + default: false + alcoholCode: + description: Code for alcohol classification, as used in the warehouse + type: integer + min: 1 + max: 11 + alcoholPercentage: + description: Percentage of alcohol in the item + type: number + format: float + min: 0 + max: 100 + volumeOfLiquidPerPack: + description: Volume of liquid per pack in liter + type: number + format: float + min: 0 + max: 100 + icpeCode: + description: Installation Classified for the Protection of the Environment, as used in the warehouse + type: integer + min: 1000 + max: 4999 + availableQuantity: + type: integer + required: &ref_142 + - productVariantId + - barcode + - unitsPerBatch + - sku + - unitCost + - productName + - categoryName + - type: object + properties: + status: + type: string + enum: + - created + - pending + - synced + expectedStockForDays: + type: + - integer + - 'null' + description: How many days stock is expected to last, based on historical data. Null if insufficient data available to create an estimate + stockStatus: + type: string + enum: + - in_stock + - soon_out_of_stock + - out_of_stock + - never_replenished + referenceId: + description: Reference for the fulfillment item, used in the warehouse + type: string + required: &ref_145 + - type + - id + - attributes + required: + - data + - jsonapi + '401': + description: Unauthorized + content: *ref_4 + '403': + description: '[Forbidden](https://jsonapi.org/format/#crud-creating-responses-403)' + content: *ref_20 + '404': + description: '[Not found](https://jsonapi.org/format/#fetching-resources-responses-404)' + content: *ref_21 + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 + '500': + description: '[Server Error](https://jsonapi.org/format/#errors)' + content: *ref_7 + parameters: + - schema: + type: string + in: header + name: Accept + description: application/vnd.api+json + - name: fulfillableIds[] + in: query + description: A set of UUIDs representing the fulfillables to check availability for + required: true + schema: + type: array + items: + type: string + format: uuid + minItems: 1 + /api/v1/fulfillment/lots: + get: + summary: List lots in the warehouse + operationId: fulfillment-list-lots + description: Returns a list of lots + tags: + - Fulfillment + responses: + '200': + description: Set of fulfillment lots + content: &ref_170 + application/vnd.api+json: + schema: + type: object + properties: + data: + type: array + items: + properties: *ref_73 + required: *ref_74 + jsonapi: + description: An object describing the server's implementation + type: object + properties: *ref_0 + additionalProperties: false + required: + - data + - jsonapi + '401': + description: Unauthorized + content: *ref_4 + '403': + description: '[Forbidden](https://jsonapi.org/format/#crud-creating-responses-403)' + content: *ref_20 + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 + '500': + description: '[Server Error](https://jsonapi.org/format/#errors)' + content: *ref_7 + parameters: + - schema: + type: string + in: header + name: Accept + description: application/vnd.api+json + - in: query + name: page[limit] + schema: + type: integer + - in: query + name: page[offset] + schema: + type: integer + - name: sort + in: query + description: Specify what attribute(s) to sort by + allowEmptyValue: false + required: false + schema: + type: string + enum: + - availableQuantity + - expiryDate + - lotNumber + - sellByDate + - fulfillmentItems.productName + - '-availableQuantity' + - '-expiryDate' + - '-lotNumber' + - '-sellByDate' + - '-fulfillmentItems.productName' + - name: filter[minAvailableQuantity] + in: query + description: Request instances with a available quantity greater or equal to a given value + required: false + schema: + type: integer + - name: filter[minSellByDate] + in: query + description: Request instances with a last sell by date greater or equal to a given value + required: false + schema: + type: string + format: datetime + - name: filter[maxSellByDate] + in: query + description: Request instances with a last sell by date smaller or equal to a given value + required: false + schema: + type: string + format: datetime + - name: include + in: query + description: 'A comma-separated list of resources to include (e.g: fulfillmentItem)' + /api/v1/brands/retailers/{retailerId}: + get: + summary: Get Retailer relation + operationId: get-brand-retailer + description: Returns brand retailer relation + tags: + - Brands + parameters: + - schema: + type: string + format: uuid + name: retailerId + in: path + required: true + description: Ankorstore retailer UUID + - schema: + type: string + in: header + name: Accept + description: application/vnd.api+json + responses: + '200': + description: Brand Retailer relation + content: &ref_171 + application/vnd.api+json: + schema: + type: object + properties: + data: + type: object + properties: &ref_147 + type: + type: string + description: '[resource object type](https://jsonapi.org/format/#document-resource-object-identification)' + id: + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + attributes: + type: object + properties: &ref_146 + automaticOrderValidationMode: + type: + - boolean + - 'null' + required: &ref_148 + - type + - id + - attributes + jsonapi: + description: An object describing the server's implementation + type: object + properties: *ref_0 + additionalProperties: false + required: + - data + - jsonapi + '401': + description: Unauthorized + content: *ref_4 + '403': + description: '[Forbidden](https://jsonapi.org/format/#crud-creating-responses-403)' + content: *ref_20 + '404': + description: '[Not found](https://jsonapi.org/format/#fetching-resources-responses-404)' + content: *ref_21 + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 + '500': + description: '[Server Error](https://jsonapi.org/format/#errors)' + content: *ref_7 + /api/v1/applications: + get: + summary: List Applications + operationId: list-applications + responses: + '200': + description: Collection of application resources + content: &ref_172 + application/vnd.api+json: + schema: + type: object + properties: + data: + title: ApplicationResource + type: object + example: &ref_149 + id: 43efbfbd-bfbd-1eef-1e6a-6200efbfbdef + type: application + attributes: + name: My sandbox + developerEmail: dev@my-app.com + clientId: k322k7frs87e8w7hri3jkke7ry7 + clientSecret: null + properties: &ref_150 + type: + type: string + const: application + id: + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + attributes: + type: object + properties: + name: + type: string + description: Application given name + developerEmail: + type: string + description: Email of the developer to contact + format: email + example: developer@application.com + clientId: + type: string + description: Client ID generated for this application + readOnly: true + clientSecret: + type: + - 'null' + description: Secret to be used for access token issuance. Can be invoked only once on application creation + required: + - name + - developerEmail + - clientId + - clientSecret + relationships: + type: object + description: Only presented if asked explicitly in the request + properties: + webhookSubscriptions: + type: object + properties: + data: + description: An array of objects each containing `type` and `id` members for to-many relationships. + type: array + items: *ref_9 + uniqueItems: true + required: &ref_151 + - id + - type + - attributes + included: + type: array + items: + anyOf: + - title: ApplicationWebhookSubscriptionResource + type: object + description: Application webhook subscription resource + properties: &ref_75 + type: + type: string + description: '[resource object type](https://jsonapi.org/format/#document-resource-object-identification)' + id: + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + attributes: + type: object + properties: + webhookUrl: + type: string + description: URL of the service where webhook request will be sent when one of the events from the list occurs + format: uri + example: https://my.app/webhook/listener + events: + type: array + uniqueItems: true + items: + type: string + signingSecret: + type: string + required: + - webhookUrl + - events + - signingSecret + required: &ref_76 + - id + - type + - attributes + jsonapi: + description: An object describing the server's implementation + type: object + properties: *ref_0 + additionalProperties: false + required: + - data + '401': + description: Unauthorized + content: *ref_4 + '403': + description: '[Forbidden](https://jsonapi.org/format/#crud-creating-responses-403)' + content: *ref_20 + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 + '500': + description: '[Server Error](https://jsonapi.org/format/#errors)' + content: *ref_7 + description: List existing application for the current authenticated user + parameters: + - schema: + type: string + in: header + name: Accept + description: application/vnd.api+json + tags: + - Applications + - Webhooks + /api/v1/webhook-subscriptions/events: + get: + summary: List Webhook Subscription Events + operationId: get-available-webhook-events + description: Returns a list of webhook events available in the system + tags: + - Webhooks + responses: + '200': + description: OK + content: + application/vnd.api+json: + schema: + type: object + required: + - data + properties: + data: + type: array + items: + type: object + required: + - id + - type + properties: + type: + type: string + description: '[resource object type](https://jsonapi.org/format/#document-resource-object-identification)' + id: + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + examples: + example: + value: + data: + - type: order.brand_created + id: 1ef27156-618d-6b1e-996c-0ef14cd127ec + - type: order.brand_accepted + id: 1ef27156-618d-6b1e-996c-0ef14cd127ec + - type: order.shipping_labels_generated + id: 1ef27156-618d-6b1e-996c-0ef14cd127ec + - type: order.shipped + id: 1ef27156-618d-6b1e-996c-0ef14cd127ec + - type: order.shipment_received + id: 1ef27156-618d-6b1e-996c-0ef14cd127ec + - type: order.shipment_refused + id: 1ef27156-618d-6b1e-996c-0ef14cd127ec + - type: order.brand_paid + id: 1ef27156-618d-6b1e-996c-0ef14cd127ec + - type: order.cancelled + id: 1ef27156-618d-6b1e-996c-0ef14cd127ec + '401': + description: Unauthorized + content: *ref_4 + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 + '500': + description: '[Server Error](https://jsonapi.org/format/#errors)' + content: *ref_7 + /api/v1/webhook-subscriptions: + post: + summary: Add Webhook Subscription to Application + operationId: add-application-webhook-subscription + tags: + - Webhooks + responses: + '201': + description: Single application webhook subscription resource response + content: &ref_77 + application/vnd.api+json: + schema: + type: object + properties: + data: + type: array + description: ApplicationWebhookSubscriptionResource object + items: + title: ApplicationWebhookSubscriptionResource + type: object + description: Application webhook subscription resource + properties: *ref_75 + required: *ref_76 + jsonapi: + description: An object describing the server's implementation + type: object + properties: *ref_0 + additionalProperties: false + required: + - data + '400': + description: Bad request + content: *ref_48 + '401': + description: Unauthorized + content: *ref_4 + '403': + description: '[Forbidden](https://jsonapi.org/format/#crud-creating-responses-403)' + content: *ref_20 + '404': + description: '[Not found](https://jsonapi.org/format/#fetching-resources-responses-404)' + content: *ref_21 + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 + '500': + description: '[Server Error](https://jsonapi.org/format/#errors)' + content: *ref_7 + description: Adds a new webhook subscription to the existing application + requestBody: + content: + application/vnd.api+json: + schema: + type: object + additionalProperties: false + properties: + data: + type: object + required: + - type + - attributes + - relationships + properties: + type: + type: string + enum: + - webhook-subscription + example: webhook-subscription + attributes: + type: object + properties: + url: + type: string + format: uri + example: https://my-app.com/webhook-listener + events: + type: array + minItems: 1 + uniqueItems: true + items: + type: string + required: + - url + - events + relationships: + type: object + properties: + applications: + type: object + properties: + data: + type: object + properties: + type: + type: string + id: + type: string + required: + - type + - id + required: + - data + required: + - applications + required: + - data + /api/v1/webhook-subscriptions/{webhookSubscriptionId}: + patch: + summary: Update Application Webhook Subscription + operationId: update-application-webhook-subscription + description: Update application subscription with given ID + tags: + - Webhooks + responses: + '200': + description: Single application webhook subscription resource response + content: *ref_77 + '401': + description: Unauthorized + content: *ref_4 + '403': + description: '[Forbidden](https://jsonapi.org/format/#crud-creating-responses-403)' + content: *ref_20 + '404': + description: '[Not found](https://jsonapi.org/format/#fetching-resources-responses-404)' + content: *ref_21 + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 + '500': + description: '[Server Error](https://jsonapi.org/format/#errors)' + content: *ref_7 + parameters: + - schema: &ref_78 + type: string + name: webhookSubscriptionId + in: path + required: true + description: Webhook Subscription ID + - name: Accept + in: header + description: application/vnd.api+json + schema: *ref_3 + requestBody: + content: + application/vnd.api+json: + schema: + type: object + properties: + data: + type: object + properties: + type: + type: string + id: + type: string + attributes: + type: object + properties: + url: + type: string + description: URL of the service where webhook request will be sent when one of the events from the list occurs + format: uri + example: https://my.app/webhook/listener + events: + type: array + minItems: 1 + uniqueItems: true + items: + type: string + example: order.brand_created + enum: + - order.brand_created + - order.brand_accepted + - order.brand_rejected + - order.shipping_labels_generated + - order.shipped + - order.shipment_received + - order.shipment_refused + - order.brand_paid + - order.cancelled + required: + - url + - events + required: + - id + - type + required: + - data + delete: + summary: Delete Application Webhook Subscription + operationId: delete-application-webhook-subscription + description: Delete application webhook subscription by given ID + tags: + - Webhooks + parameters: + - schema: *ref_78 + name: webhookSubscriptionId + in: path + required: true + description: Webhook Subscription ID + - name: Accept + in: header + description: application/vnd.api+json + required: true + schema: &ref_155 + type: string + default: application/vnd.api+json + responses: + '200': + description: OK + '401': + description: Unauthorized + content: *ref_4 + '404': + description: '[Not found](https://jsonapi.org/format/#fetching-resources-responses-404)' + content: *ref_21 + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 + '500': + description: '[Server Error](https://jsonapi.org/format/#errors)' + content: *ref_7 + /api/v1/operations: + post: + summary: Bulk Operations + operationId: post-api-v1-operations + responses: + '200': + description: Example response + content: &ref_173 + application/vnd.api+json: + schema: + type: object + properties: + atomic:results: + type: array + items: + title: BulkOperationResult + type: object + properties: &ref_152 + data: + type: object + required: + - type + - id + properties: + type: + type: string + description: '[resource object type](https://jsonapi.org/format/#document-resource-object-identification)' + id: + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + attributes: + type: object + required: &ref_153 + - data + description: Single operation result in the list of results in the bulk operation response + examples: &ref_154 + - data: + type: productVariant + id: 6b1a9a20-297c-4f26-8f00-70ece7c37ecd + attributes: + foo: bar + '401': + description: Unauthorized + content: *ref_4 + '404': + description: '[Not found](https://jsonapi.org/format/#fetching-resources-responses-404)' + content: *ref_21 + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 + '422': + description: 'Unprocessable Entity : Data provided are invalid' + content: *ref_64 + tags: + - Stock Management + description: Multiple operations on different resources by a single request + requestBody: + content: &ref_188 + application/vnd.api+json: + schema: + type: object + properties: + atomic:operations: + type: array + maxItems: 50 + minItems: 1 + items: + type: object + properties: + op: + type: string + enum: + - update + data: + anyOf: + - title: ProductVariantStockUpdateSetIsAlwaysInStockRequest + type: object + examples: *ref_79 + properties: *ref_80 + required: *ref_81 + description: A request schema to update product variant stock value by setting option "always in stock" to true. It will also reset any possibly previously existed explicit stock quantities. + - title: ProductVariantStockUpdateSetStockQuantity + type: object + description: A request schema to update product variant stock value by setting explicit stock quantity. + properties: *ref_82 + required: *ref_83 + examples: *ref_84 + required: + - op + - data + required: + - atomic:operations + examples: {} + /api/testing/orders/create: + post: + summary: Create Test Order + operationId: brand-create-test-order + description: | + Creates a test order ready to be confirmed based on the options provided. + **ONLY AVAILABLE IN SANDBOX ENVIRONMENT**. + tags: + - Testing + parameters: + - name: include + in: query + description: '[See supported values](https://ankorstore.github.io/api-docs/#tag/Ordering/Working-with-Internal-Orders)' + allowEmptyValue: true + required: false + schema: *ref_59 + - schema: + type: string + in: header + name: Accept + description: application/vnd.api+json + - schema: + type: string + in: header + name: Content-Type + description: application/vnd.api+json + requestBody: + description: The options that can be provided when creating a test order + content: + application/vnd.api+json: + schema: + description: Options + type: + - object + - 'null' + properties: + retailerId: + type: + - string + - 'null' + description: The Retailer Id + itemQuantity: + type: + - integer + - 'null' + description: If productVariants/productOptions are not provided, then this will set the quantity each order item created. + minimum: 1 + maximum: 999 + productVariants: + type: + - array + - 'null' + description: List of variant IDs and their quantities. Cannot be included with productOptions. + uniqueItems: true + items: + type: object + properties: + id: + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + itemQuantity: + type: integer + minimum: 1 + maximum: 999 + productOptions: + type: + - array + - 'null' + description: List of option IDs and their quantities - Only use if you are currently using the old options system. Cannot be included with productVariants + uniqueItems: true + items: + type: object + properties: + id: + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + itemQuantity: + type: integer + minimum: 1 + maximum: 999 + examples: + use-existing-retailer: + value: + retailerId: 5ee4d438-0489-4634-aa60-746f485af458 + use-product-variants: + value: + retailerId: 5ee4d438-0489-4634-aa60-746f485af458 + productVariants: + - id: 73ace86a-db9c-408f-b28f-b478694988c8 + quantity: 3 + - id: 88f24110-dc42-42a4-abf0-857f90efce7d + quantity: 3 + use-product-options: + value: + retailerId: 5ee4d438-0489-4634-aa60-746f485af458 + productOptions: + - id: 73ace86a-db9c-408f-b28f-b478694988c8 + quantity: 3 + - id: 88f24110-dc42-42a4-abf0-857f90efce7d + quantity: 3 + no-options-provided: + description: No options are required + value: {} + responses: + '200': + description: '[OK](https://jsonapi.org/format/#fetching-resources-responses-200)' + content: + application/vnd.api+json: + schema: + title: Order Get + type: object + additionalProperties: false + examples: *ref_60 + properties: *ref_61 + required: *ref_62 + examples: + example: + value: + jsonapi: + version: '1.0' + data: + type: order + id: 1ecb023e-8ec0-6d5c-a477-0242ac170007 + attributes: + status: brand_confirmed + reference: 3434273911 + brandCurrency: EUR + brandNetAmount: 10229 + brandTotalAmount: 10940 + brandTotalAmountVat: 602 + brandTotalAmountWithVat: 11542 + brandRejectReason: null + retailerRejectReason: null + retailerCancellationRequestReason: null + billingName: Charles Attan + billingOrganisationName: Jumbo + billingStreet: Kortricklaan 101 + billingPostalCode: 8121 GW + billingCity: Arnhem + billingCountryCode: NL + submittedAt: '2022-03-17T13:19:33+00:00' + shippedAt: null + brandPaidAt: null + createdAt: '2022-02-01T14:37:10+00:00' + updatedAt: '2022-03-31T15:10:07+00:00' + shippingMethod: null + shippingOverview: + availableShippingMethods: + - custom + - ankorstore + shipToAddress: + name: John Smith + organisationName: Test + street: Test Street + city: Commentry + postalCode: '03633' + countryCode: FR + expectedShippingDates: + minimum: '2022-03-22T00:00:00+00:00' + maximum: '2022-03-24T23:59:59+00:00' + provider: null + tracking: null + latestQuote: null + parcels: [] + transaction: null + '406': + description: Not Acceptable + content: *ref_5 + '415': + description: Unsupported Media Type + content: *ref_6 +components: + schemas: + failure: + type: object + additionalProperties: false + properties: *ref_1 + required: *ref_2 + meta: + description: Non-standard meta-information that can not be represented as an attribute or relationship. + type: object + additionalProperties: true + relationshipToOne: + description: References to other resource objects in a to-one (`relationship`). Relationships can be specified by including a member in a resource's links object. + type: object + required: *ref_12 + properties: *ref_13 + additionalProperties: false + relationshipToMany: + description: An array of objects each containing `type` and `id` members for to-many relationships. + type: array + items: *ref_9 + uniqueItems: true + linkage: + description: Resource identification present in Resource Objects and Resource Identifier Objects. + type: object + required: *ref_12 + properties: *ref_13 + additionalProperties: false + jsonapi: + description: An object describing the server's implementation + type: object + properties: *ref_0 + additionalProperties: false + error: + type: object + properties: *ref_85 + additionalProperties: false + id: + type: string + description: '[resource object identifier (uuid)](https://jsonapi.org/format/#document-resource-object-identification)' + format: uuid + type: + type: string + description: '[resource object type](https://jsonapi.org/format/#document-resource-object-identification)' + money: + type: integer + description: Lowest denomination of the currency this amount belongs to. + massUnit: + type: string + description: The unit of mass + enum: *ref_67 + distanceUnit: + type: string + description: The unit of distance + enum: *ref_66 + paginationMeta: + type: object + description: Meta with Pagination Details + required: *ref_17 + additionalProperties: true + properties: *ref_18 + paginationLinks: + description: Pagination navigation links. If a link does not exist then you cannot paginate any further in that direction. + type: object + properties: *ref_19 + CurrencyRate: + type: object + properties: *ref_86 + Order: + description: The resource object for Order + type: object + additionalProperties: false + title: Order Resource + properties: *ref_40 + required: *ref_41 + OrderItem: + title: Order Item Resource + type: object + additionalProperties: false + examples: *ref_52 + properties: *ref_53 + required: *ref_54 + BillingItem: + title: Billing Item Resource + type: object + additionalProperties: false + examples: *ref_55 + properties: *ref_56 + required: *ref_57 + ProductVariant: + title: Product Variant Resource + description: Variant details for a given product. Unique products will have one single variant. + type: object + additionalProperties: false + examples: *ref_14 + properties: *ref_15 + required: *ref_16 + ProductOption: + title: Product Option Resource + description: A unique option for a product + type: object + additionalProperties: false + examples: *ref_45 + properties: *ref_46 + required: *ref_47 + Product: + title: Product Resource + description: The resource object for Product + type: object + additionalProperties: false + properties: *ref_10 + required: *ref_11 + Retailer: + title: Retailer Resource + type: object + additionalProperties: false + example: *ref_49 + properties: *ref_50 + required: *ref_51 + CurrencyRateResource: + properties: *ref_87 + required: *ref_88 + UserConfig: + type: object + properties: *ref_89 + UserConfigResource: + properties: *ref_90 + required: *ref_91 + ProductCollection: + type: object + title: Product Collection + required: *ref_92 + properties: *ref_93 + additionalProperties: false + ProductGet: + type: object + additionalProperties: false + title: Product Get + properties: *ref_94 + examples: *ref_95 + required: *ref_96 + ProductVariantCollection: + type: object + required: *ref_97 + properties: *ref_98 + additionalProperties: false + title: Product Variant Collection + ProductVariantStockUpdateSetStockQuantity: + title: ProductVariantStockUpdateSetStockQuantity + type: object + description: A request schema to update product variant stock value by setting explicit stock quantity. + properties: *ref_82 + required: *ref_83 + examples: *ref_84 + ProductVariantStockUpdateSetIsAlwaysInStock: + title: ProductVariantStockUpdateSetIsAlwaysInStockRequest + type: object + examples: *ref_79 + properties: *ref_80 + required: *ref_81 + description: A request schema to update product variant stock value by setting option "always in stock" to true. It will also reset any possibly previously existed explicit stock quantities. + OperationSource: + title: OperationSource + description: Source of the operation + type: string + enum: *ref_24 + OperationStatus: + title: OperationStatus + type: string + enum: *ref_99 + OperationType: + title: OperationType + description: Operation type + type: string + enum: *ref_100 + updateFields: + title: updateFields + description: List of fields or group of fields that will be updated on provided products + type: array + items: *ref_101 + Operation: + title: Operation + description: An operation resource + type: object + required: *ref_25 + properties: *ref_26 + CallbackEvent: + title: CallbackEvent + type: object + required: *ref_102 + properties: *ref_103 + OperationProductImageSchema: + type: object + description: Image + properties: *ref_31 + AgeAttributeSchema: + type: object + description: Age attribute + properties: *ref_104 + GenderAttributeSchema: + type: object + description: Gender attribute + properties: *ref_105 + OperationProductShapeSchema: + type: object + description: Shape properties of the item + properties: *ref_30 + OperationProductVariantOptionSchema: + type: object + description: | + Specific options related to a variant + > Should not be provided in the case of having only one variant > Combination of values should be unique in the case of multiple variants + properties: *ref_106 + OperationProductVariantSchema: + type: object + description: Variant of the product + properties: *ref_107 + OperationProductSchema: + type: object + required: *ref_108 + properties: *ref_109 + OperationIssue: + type: object + properties: *ref_110 + OperationResult: + title: OperationResult + type: object + required: *ref_111 + properties: *ref_112 + OperationReportSchema: + title: Product Integration Resource list + description: Product Integration Resource list + type: object + additionalProperties: false + properties: *ref_113 + ExternalIntegration: + type: object + properties: *ref_35 + required: *ref_36 + ExternalIntegrationResource: + type: object + properties: *ref_114 + MasterOrder: + title: Master Order + type: object + additionalProperties: false + properties: *ref_39 + OrderWorkflowStatus: + type: string + example: ankor_confirmed + enum: *ref_44 + ShippingLabelCurrentStatus: + type: object + properties: *ref_37 + ShippingLabelParcelWithTrackedPackage: + description: Shipping Label Parcel + type: object + properties: *ref_115 + required: *ref_116 + OrderShippingOverview: + title: Order Resource -> Shipping Overview + description: Contains all information related to either shipping method (`ankorstore` or `custom`). This field is ONLY included when fetching a single order at a time. + type: object + properties: *ref_117 + required: *ref_118 + ExternalOrder: + type: object + title: External Order Resource + description: The resource object for External Order + additionalProperties: false + properties: *ref_42 + Shipment: + title: Order shipment + type: object + additionalProperties: false + properties: *ref_119 + MasterOrderList: + title: Master Order List + type: object + additionalProperties: false + properties: *ref_120 + MasterOrderGet: + title: Master Order Get + type: object + additionalProperties: false + properties: *ref_121 + FulfillmentOrderStatus: + type: string + enum: *ref_43 + readOnly: true + FulfillmentOrderItem: + type: object + properties: *ref_122 + required: *ref_123 + FulfillmentOrderShippedItem: + type: object + properties: *ref_124 + required: *ref_125 + RecipientType: + type: string + enum: *ref_126 + default: business + description: The type of recipient for a fulfillment order + FulfillmentOrder: + type: object + properties: *ref_127 + required: *ref_128 + FulfillmentOrderResource: + properties: *ref_70 + required: *ref_71 + FulfillmentOrderStatusUpdate: + description: Fulfillment order status update + type: object + properties: *ref_129 + FulfillmentOrderStatusUpdateResource: + properties: *ref_72 + OrderCollection: + title: Order Collection + type: object + required: *ref_130 + properties: *ref_131 + additionalProperties: false + OrderGet: + title: Order Get + type: object + additionalProperties: false + examples: *ref_60 + properties: *ref_61 + required: *ref_62 + ListShippingQuotesResponse: + type: object + required: *ref_132 + properties: *ref_133 + ConfirmSippingQuoteResponse: + type: object + properties: *ref_134 + ShippingLabelParcel: + description: Shipping Label Parcel. Packages can be up to 400 cm in length and girth combined + type: object + properties: *ref_68 + required: *ref_69 + FulfillmentFulfillable: + description: A fulfillable entity, which can be either an item or a bundle (set of items) + type: object + properties: *ref_135 + required: *ref_136 + FulfillmentFulfillableResource: + properties: *ref_137 + required: *ref_138 + FulfillmentLot: + type: object + properties: *ref_139 + required: *ref_140 + FulfillmentLotResource: + properties: *ref_73 + required: *ref_74 + FulfillmentItemBase: + title: FulfillmentItem + type: object + properties: *ref_141 + required: *ref_142 + FulfillmentItem: + allOf: *ref_143 + FulfillmentItemResource: + properties: *ref_144 + required: *ref_145 + BrandRetailer: + type: object + properties: *ref_146 + BrandRetailerResource: + type: object + properties: *ref_147 + required: *ref_148 + ApplicationResource: + title: ApplicationResource + type: object + example: *ref_149 + properties: *ref_150 + required: *ref_151 + ApplicationWebhookSubscriptionResource: + title: ApplicationWebhookSubscriptionResource + type: object + description: Application webhook subscription resource + properties: *ref_75 + required: *ref_76 + BulkOperationResult: + title: BulkOperationResult + type: object + properties: *ref_152 + required: *ref_153 + description: Single operation result in the list of results in the bulk operation response + examples: *ref_154 + parameters: + acceptInHeader: + name: Accept + in: header + description: application/vnd.api+json + schema: *ref_3 + acceptInHeaderRequired: + name: Accept + in: header + description: application/vnd.api+json + required: true + schema: *ref_155 + pageLimit: + name: page[limit] + in: query + description: limit the amount of results returned + required: false + schema: *ref_32 + pageBefore: + name: page[before] + in: query + description: show items before the provided ID (uuid format) + required: false + schema: *ref_33 + pageAfter: + name: page[after] + in: query + description: show items after the provided ID (uuid format) + required: false + schema: *ref_34 + productIdInPath: + name: product + in: path + required: true + schema: *ref_156 + productIncludeResourcesInQuery: + name: include + in: query + description: '[Include Product Variants](https://ankorstore.github.io/api-docs/#tag/Product/Working-with-Products/Including-Product-Variants)' + allowEmptyValue: true + required: false + schema: *ref_157 + productVariantInPath: + name: productVariant + in: path + required: true + schema: *ref_22 + OperationUrlId: + name: operationId + in: path + required: true + schema: *ref_29 + description: The unique identifier of the operation + orderIncludeResourcesInQuery: + name: include + in: query + allowEmptyValue: true + required: false + schema: *ref_38 + orderIdInPath: + name: master_order + in: path + required: true + schema: *ref_158 + parameters-orderIdInPath: + name: order + in: path + required: true + schema: *ref_65 + parameters-orderIncludeResourcesInQuery: + name: include + in: query + description: '[See supported values](https://ankorstore.github.io/api-docs/#tag/Ordering/Working-with-Internal-Orders)' + allowEmptyValue: true + required: false + schema: *ref_59 + quoteIdInPath: + name: quote + in: path + required: true + schema: *ref_159 + webhookSubscriptionId: + schema: *ref_78 + name: webhookSubscriptionId + in: path + required: true + description: Webhook Subscription ID + securitySchemes: + ProductionOAuth2ClientCredentials: + type: oauth2 + flows: + clientCredentials: + tokenUrl: https://www.ankorstore.com/oauth/token + refreshUrl: https://www.ankorstore.com/oauth/token + scopes: {} + TestOauth2ClientCredentials: + type: oauth2 + flows: + clientCredentials: + tokenUrl: https://www.public.ankorstore-sandbox.com/oauth/token + refreshUrl: https://www.public.ankorstore-sandbox.com/oauth/token + scopes: {} + responses: + NoContent: + description: No content + content: *ref_63 + BadRequest: + description: Bad request + content: *ref_48 + Unauthorized: + description: Unauthorized + content: *ref_4 + Forbidden: + description: '[Forbidden](https://jsonapi.org/format/#crud-creating-responses-403)' + content: *ref_20 + NotFound: + description: '[Not found](https://jsonapi.org/format/#fetching-resources-responses-404)' + content: *ref_21 + UnprocessableEntity: + description: 'Unprocessable Entity : Data provided are invalid' + content: *ref_64 + ServerError: + description: '[Server Error](https://jsonapi.org/format/#errors)' + content: *ref_7 + TooManyRequests: + description: '[Too Many Requests](https://jsonapi.org/format/#errors)' + content: + application/vnd.api+json: + schema: + type: object + additionalProperties: false + properties: *ref_1 + required: *ref_2 + example: + jsonapi: + version: '1.0' + errors: + - detail: Too Many Requests + status: '429' + Conflict: + description: Conflict + content: + application/vnd.api+json: + schema: + type: object + additionalProperties: false + properties: *ref_1 + required: *ref_2 + example: + jsonapi: + version: '1.0' + errors: + - detail: Conflict + status: '409' + NotAcceptable: + description: Not Acceptable + content: *ref_5 + UnsupportedMediaType: + description: Unsupported Media Type + content: *ref_6 + CurrencyRateCollectionResponse: + description: Set of currency exchange rates + content: *ref_160 + UserConfigResponse: + description: User config + content: *ref_8 + ProductVariantResponse: + description: Single product-variant resource response with stock details + content: *ref_23 + GetOperationItemResponse: + content: *ref_28 + CreateDeleteOperationResponse: + content: *ref_161 + AddProductsToOperationResponse: + content: *ref_162 + ExternalIntegrationResponse: + description: Single External Integration + content: *ref_163 + BrandResponse: + description: Single Brand resource response + content: *ref_164 + FulfillmentOrdersCollectionResponse: + description: Set of fulfillment orders + content: *ref_165 + FulfillmentOrdersRelationshipResponse: + description: Set of fulfillment order id and links + content: *ref_166 + InternalOrderFulfillabilityError: + description: Blockers that disqualify an order from fulfillment via Ankorstore logistics + content: *ref_167 + FulfillmentOrderResponse: + description: Single fulfillment order + content: *ref_168 + FulfillmentFulfillableCollectionResponse: + description: Set of fulfillment fullfilables + content: *ref_169 + LotsCollectionResponse: + description: Set of fulfillment lots + content: *ref_170 + BrandRetailerResponse: + description: Brand Retailer relation + content: *ref_171 + ApplicationsCollectionResponse: + description: Collection of application resources + content: *ref_172 + ApplicationWebhookSubscriptionResponse: + description: Single application webhook subscription resource response + content: *ref_77 + BulkOperationsSuccessResponse: + description: Example response + content: *ref_173 + examples: + CreateOperationRequest: + value: *ref_174 + CreateUpdateOperationRequest: + value: *ref_175 + OperationCreatedResponse: + value: *ref_176 + OperationStartedResponse: + value: *ref_177 + OperationSucceededResponse: + value: *ref_178 + CreateDeleteOperationRequest: + value: *ref_179 + DeleteOperationStartedResponse: + value: *ref_180 + AddProductsToOperationRequest: + value: *ref_181 + OperationReportExample: + value: *ref_182 + requestBodies: + CreateOperation: + content: *ref_183 + CallbackEvent: + content: *ref_27 + CreateDeleteOperation: + content: *ref_184 + ModifyOperation: + content: *ref_185 + AddProductsToOperation: + content: *ref_186 + UpdateExternalIntegrationStatusRequest: + required: true + content: *ref_187 + BulkOperationsProductVariantStockUpdate: + content: *ref_188 +x-tagGroups: + - name: Main + tags: + - How to work with API + - Authentication + - Available APIs + - Webhook Subscription + - Testing API + - Fair Use Statement + - name: API Resource Endpoints + tags: + - Applications + - Brands + - General + - User + - Catalog + - Catalog Integrations + - Integration + - Ordering + - Shipping + - Fulfillment + - Webhooks + - Testing + - Deprecated