From 5e78dfdc8650ffa559ff4638e105c89b0d5d325d Mon Sep 17 00:00:00 2001 From: roman-kovalev-aks Date: Wed, 18 Oct 2023 18:53:44 +0000 Subject: [PATCH] =?UTF-8?q?Deploying=20to=20main=20from=20@=20ankorstore/a?= =?UTF-8?q?nkorstore@f637336cba84a59be8a5301cd90aa0b6a4840f8d=20?= =?UTF-8?q?=F0=9F=9A=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- pull/36253/index.html | 2922 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 2922 insertions(+) create mode 100644 pull/36253/index.html diff --git a/pull/36253/index.html b/pull/36253/index.html new file mode 100644 index 0000000..f5b6123 --- /dev/null +++ b/pull/36253/index.html @@ -0,0 +1,2922 @@ + + + + + + Ankorstore Public API + + + + + + + + + + + +
Ankorstore
API docs by Redocly

Ankorstore Public API (1.0.0)

Download OpenAPI specification:Download

Ankorstore Support: api@ankorstore.com URL: https://www.ankorstore.com License: CC0 1.0 Universal
Ankorstore API Specification

Overview

Welcome to the initial release of the Ankorstore API. The documentation is a continual process so please provide feedback.

+

API Specification/Schema

This API follows the Ankorstore API Specification which is based on the JSON:API specification.

+

Please give our specification a thorough read to understand how our request and response formats work.

+

What is currently supported

From a high level the API currently supports the following actions:

+ +

Recommendations on interacting with the API

It is recommended that you only use the order list endpoint to retrieve newly created orders 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 order retrieval endpoint if you wish to fetch more information about each order.

+

Testing

To test the API you can use our public sandbox environment

+
+ +

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.

+

Working with our API

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.

+

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 if its list based or not.

+

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.

+

Pagination

Ankorstore uses cursor based pagination. In the root level object for pagination supported endpoints you will find a meta object containing pagination information:

+
  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:

+
{
+  "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:

+
  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:

+
{
+  "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"
+  }
+}
+
+

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.

+

Authentication

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 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 section.

+
+ +

To generate a token pass in your client_id and client_secret:

+
{
+  "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

+
+ +

You will receive an access_token:

+
{
+  "token_type": "Bearer",
+  "expires_in": 3600,
+  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiI5NWZmZDJkYy0zYjE5LTQzMWQtYjJkYi03ZTNmMWQxMDA1MWUiLCJqdGkiOiI3NzExN2Y3ODQ2YWVkMjQyYTVmYWVlZDZmOGRjMjcyNmQyNjIzYTZmODlmMjZkMTVlNDk0NDE1ZDAyY2E3MDU5M2M4YTU3ZjllN2Y4OTZjOSIsImlhdCI6MTY0OTI1OTg4MS4yMjQ0NjIsIm5iZiI6MTY0OTI1OTg4MS4yMjQ0NjcsImV4cCI6MTY0OTI2MzQ4MS4yMTM2NjcsInN1YiI6IjE1OTUiLCJzY29wZXMiOlsiKiJdfQ.E3CirFN_hgQZmxG10VSXZPs1sYml8cnsYXgzt7Zzr3sG6YT-soEvDmlsiJyMXjiG_duVfsFwut2JXPfL9N2NZ0LTdWtPddz6rxTRF4o-gId8Z62ROOJJvHVNmObl_ZW6_6fKMPgLX_bIkFO4twh6_DfXE7ju40iybwBmPMtzYaf8_i03truuIy7T1oSldvsEgrdMSl4uYfeAj24nnW7IYsMZujBHBhSZxlDVIzGb1ZaK2L34pXwwqrIXg_572R22s9e5dyejHBBjWC0gbUvo1F2RL5Um4UEtUe6_ImvPXQAB4DY55TK_JwIIiEAAxbUJ1gnpRB9d-Zift2akFhwoESMOqd3JGsatj0Poync-NwUmZGO8bI3sjP2jcsKfTSwMNap4B2vaerW_NOP3BX-3pqUTSqSOD2jFtKwE3Etxgqub38DBQ-9p7w9pVSxBcTWb583t25zCLInE9PXxpBtYswictIAlziXFzZpsGgZiyi9aXN_oMttAknOuYsEfz8SsZxJp9qnjiprUcfGHnjOvDum6rK4xhKsFrGEw2UmUkO9QTEi7Co_GclaMUOrZgLD5eF5dVCMS7cbNZESF3O30Knn1fAwXV7iGJeHEmEZHKueEOernNVyRWCoSq7K6qQZmzNJJ06IJXUYIsao6e9wL0w47NmbyhbrHKfleiRPKRxw"
+}
+
+

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):

+
{
+  "method": "get",
+  "headers": {
+    "accept": "application/json",
+    "Authorization": "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiI5NWZmZDJkYy0zYjE5LTQzMWQtYjJkYi03ZTNmMWQxMDA1MWUiLCJqdGkiOiI3NzExN2Y3ODQ2YWVkMjQyYTVmYWVlZDZmOGRjMjcyNmQyNjIzYTZmODlmMjZkMTVlNDk0NDE1ZDAyY2E3MDU5M2M4YTU3ZjllN2Y4OTZjOSIsImlhdCI6MTY0OTI1OTg4MS4yMjQ0NjIsIm5iZiI6MTY0OTI1OTg4MS4yMjQ0NjcsImV4cCI6MTY0OTI2MzQ4MS4yMTM2NjcsInN1YiI6IjE1OTUiLCJzY29wZXMiOlsiKiJdfQ.E3CirFN_hgQZmxG10VSXZPs1sYml8cnsYXgzt7Zzr3sG6YT-soEvDmlsiJyMXjiG_duVfsFwut2JXPfL9N2NZ0LTdWtPddz6rxTRF4o-gId8Z62ROOJJvHVNmObl_ZW6_6fKMPgLX_bIkFO4twh6_DfXE7ju40iybwBmPMtzYaf8_i03truuIy7T1oSldvsEgrdMSl4uYfeAj24nnW7IYsMZujBHBhSZxlDVIzGb1ZaK2L34pXwwqrIXg_572R22s9e5dyejHBBjWC0gbUvo1F2RL5Um4UEtUe6_ImvPXQAB4DY55TK_JwIIiEAAxbUJ1gnpRB9d-Zift2akFhwoESMOqd3JGsatj0Poync-NwUmZGO8bI3sjP2jcsKfTSwMNap4B2vaerW_NOP3BX-3pqUTSqSOD2jFtKwE3Etxgqub38DBQ-9p7w9pVSxBcTWb583t25zCLInE9PXxpBtYswictIAlziXFzZpsGgZiyi9aXN_oMttAknOuYsEfz8SsZxJp9qnjiprUcfGHnjOvDum6rK4xhKsFrGEw2UmUkO9QTEi7Co_GclaMUOrZgLD5eF5dVCMS7cbNZESF3O30Knn1fAwXV7iGJeHEmEZHKueEOernNVyRWCoSq7K6qQZmzNJJ06IJXUYIsao6e9wL0w47NmbyhbrHKfleiRPKRxw"
+  },
+  "baseUrl": "https://www.ankorstore.com",
+  "url": "/api/v1/me",
+}
+
+

If successful you will receive a 200 response:

+
{
+  "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.

+

Webhooks

Subscribing

To subscribe to events please go to the Applications section in your account area.

+

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

+
{
+  "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
    • +
+

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:

+
$payloadJson = json_encode($payload);
+$signature = hash_hmac('sha256', $payloadJson, $secret);
+
+

You can calculate the webhook's signature and compare it to the one present on the request.

+

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.

+

Currency

List of latest currency rates

Returns a list of the latest currency rates

+
Authorizations:
ProductionOAuth2ClientCredentials
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

+

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "type": "string",
      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "attributes": {
        }
      }
    ],
  • "jsonapi": {
    • "version": "string",
    • "meta": { }
    }
}

Navigation

Get Navigation Menu Items

Returns the list of items in the navigation menu.

+
Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
code
required
string
Example: main

The unique code (slug) for the menu

+

Responses

Response samples

Content type
application/vnd.api+json
{
  • "jsonapi": {
    • "version": "1.0"
    },
  • "data": [
    • {
      • "id": "1ee1a39f-34df-6c9c-b59e-0242ac150007",
      • "type": "nav-item",
      • "attributes": {
        },
      • "meta": {
        }
      },
    • {
      • "id": "1ee1a39f-3555-6fe6-a4a3-0242ac150007",
      • "type": "nav-item",
      • "attributes": {
        },
      • "meta": {
        }
      },
    • {
      • "id": "1ee1a39f-3556-6ed2-aedc-0242ac150007",
      • "type": "nav-item",
      • "attributes": {
        },
      • "meta": {
        }
      },
    • {
      • "id": "1ee1a39f-3557-685a-bcee-0242ac150007",
      • "type": "nav-item",
      • "attributes": {
        },
      • "meta": {
        }
      },
    • {
      • "id": "1ee1a39f-3558-6192-93e2-0242ac150007",
      • "type": "nav-item",
      • "attributes": {
        },
      • "meta": {
        }
      },
    • {
      • "id": "1ee1a39f-3558-6a7a-8490-0242ac150007",
      • "type": "nav-item",
      • "attributes": {
        },
      • "meta": {
        }
      },
    • {
      • "id": "1ee1a39f-3559-6632-b8c6-0242ac150007",
      • "type": "nav-item",
      • "attributes": {
        },
      • "meta": {
        }
      },
    • {
      • "id": "1ee1a39f-355a-600a-8b1b-0242ac150007",
      • "type": "nav-item",
      • "attributes": {
        },
      • "meta": {
        }
      },
    • {
      • "id": "1ee1a39f-3797-6480-8de8-0242ac150007",
      • "type": "nav-item",
      • "attributes": {
        },
      • "meta": {
        }
      }
    ]
}

Order

Working with Orders

Here you will find information about the order resource and it's sub-resources. If you need further information please refer to the API specification.

+

Including order items, retailer and other information

When retrieving the individual order via the API, you may find it lacking in certain information such as retailer, order items etc.

+
+ +

Includes

+

For every endpoint that returns the 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.productOption, orderItems.productOption.product, orderItems.productVariant and orderItems.productVariant.product.

+

Please note that, if you include orderItems.productOption 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.productOption.product

+

Important Fields within 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 of 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:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
StatusDescription
ankor_confirmedThe order has been confirmed by Ankorstore and now a decision can be made whether to accept or reject this order.
rejectedThe order has been rejected, Ankorstore needs to approve this rejection. If it does, the status will moved to cancelled.
brand_confirmedThe order has been accepted. it now needs to be shipped to the retailer.
shipping_labels_generatedThe order has been shipped with Ankorstore and the labels have been generated - these are now available in the order resource data within shippingOverview.
fulfillment_requestedThe 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.
shippedThe order has either been picked up by an Ankorstore carrier (e.g UPS) or the brand has chosen to ship with their own carrier.
receivedThe 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_refusedThe 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.
invoicedThe final invoice has been issued for this order.
brand_paidThe brand has been paid in full for this order.
cancelledThe 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 for further details.

+
+ +

Shipping Method shippingMethod

+

What shipment method has been chosen for this order. Either ankorstore for using Ankorstores 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 Availaiblity

+

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 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 an order for further details.

+

Accepting an 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:

+
{
+    "data": {
+        "type": "brand-validates"
+    }
+}
+
+

The order will move from ankor_confirmed to brand_confirmed.

+

Accepting an 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.

+
{
+    "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 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

+
{
+    "data": {
+        "type": "brand-rejects",
+        "attributes": {
+            "rejectType": "ORDER_ITEMS_PRICES_INCORRECT"
+        }
+    }
+}
+
+

Example rejection with OTHER

+
{
+    "data": {
+        "type": "brand-rejects",
+        "attributes": {
+            "rejectType": "OTHER",
+            "rejectReason": "a different reason"
+        }
+    }
+}
+
+

The order will move from ankor_confirmed to cancelled.

+

Resetting an 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

+
{
+    "data": {
+        "type": "brand-resets-shipping-labels-generation",
+        "attributes": {
+            "resetType": "BRAND_PUT_WRONG_WEIGHT_DIMENSIONS"
+        }
+    }
+}
+
+

Example reset shipping labels with OTHER

+
{
+    "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.

+

Shipping an 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.

+
+ +

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: <br> 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: <br> shipping-quotes/:quoteId/confirm]
+    B.NO --> A
+    A[Start] --> C[I want to ship with custom: <br> 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:

+
{
+  "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 :

+
{
+  "shippingCostsOverview": {
+    "amount": 5160,
+    "currency": "EUR",
+    "type": "fee"
+  }
+}
+
+

Refund payload example :

+
{
+  "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):

+
{
+    "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.

+

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 : <br> orders/:orderId/ship/custom
+  participant SC as Confirm : <br> 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:

+
 {
+   "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 : <br> orders/:orderId/shipping-quotes
+  participant SC as Confirm shipping : <br> 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.

+

Shipping an Order (Deprecated)

+ + + + + +
:zap: This documentation is deprecrated
+

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:

+
{
+  "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 :

+
{
+  "shippingCostsOverview": {
+    "amount": 5160,
+    "currency": "EUR",
+    "type": "fee"
+  }
+}
+
+

Refund payload example :

+
{
+  "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.

+

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.

+

List Orders

Returns all orders, can be filtered by retailer ID or by order status.

+
Authorizations:
ProductionOAuth2ClientCredentials
query Parameters
filter[retailer]
string
Example: filter[retailer]=23e4567-e89b-12d3-a456-426614174000

Retailer Id

+
filter[status]
string (OrderWorkflowStatus)
Enum: "ankor_confirmed" "rejected" "brand_confirmed" "shipping_labels_generated" "fulfillment_requested" "shipped" "reception_refused" "received" "invoiced" "brand_paid" "cancelled"
Example: filter[status]=ankor_confirmed

Order Status

+
page[limit]
integer <int64>

limit the amount of results returned

+
page[before]
string

show items before the provided ID (uuid format)

+
page[after]
string

show items after the provided ID (uuid format)

+
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

+

Responses

Response samples

Content type
application/vnd.api+json
{
  • "meta": {
    • "page": {
      • "from": "123e4567-e89b-12d3-a456-426614174000",
      • "hasMore": true,
      • "perPage": 2,
      • "to": "1ecb023e-7ec0-6d5c-a477-0242ac170008"
      }
    },
  • "jsonapi": {
    • "version": "1.0"
    },
  • "links": {},
  • "data": [
    • {
      • "type": "orders",
      • "id": "123e4567-e89b-12d3-a456-426614174000",
      • "attributes": {
        },
      • "relationships": {
        }
      },
    • {
      • "type": "orders",
      • "id": "1ecb023e-7ec0-6d5c-a477-0242ac170007",
      • "attributes": {
        },
      • "relationships": {
        }
      }
    ]
}

Get Order

Retrieve a specific order

+
Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
order
required
string <uuid> (id)
Default: "079ba9ad-dcdb-4dda-ba0a-1174dad313c5"
query Parameters
include
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

+

Responses

Response samples

Content type
application/vnd.api+json
{
  • "jsonapi": {
    • "version": "1.0"
    },
  • "data": {
    • "type": "order",
    • "id": "1ecb023e-7ec0-6d5c-a477-0242ac170009",
    • "attributes": {
      • "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": {
        }
      }
    },
  • "included": [
    • {
      • "type": "retailer",
      • "id": "3b656e82-0260-1ecb-9e4c-0242ac170007",
      • "attributes": {
        }
      }
    ]
}

Transition an order

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.

+
Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
order
required
string <uuid> (id)
Default: "079ba9ad-dcdb-4dda-ba0a-1174dad313c5"
query Parameters
include
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

+
Request Body schema: application/vnd.api+json
Brand Accepts Payload (object) or Brand Rejects Payload (object) or Brand Resets Shipping Labels Generation (object)
One of
type
required
string
Value: "brand-validates"

The transition to use

+
object
Array of objects unique

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.

+
Array
id
required
string

Order Item Uuid

+
type
required
string
Value: "order-items"
required
object

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "data": {
    • "type": "brand-validates"
    }
}

Response samples

Content type
application/vnd.api+json
Example
{
  • "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": {
        }
      }
    }
}

[Deprecated] Accept Order Deprecated

[Deprecated] Please use the Order Transition endpoint.

+
Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
order
required
string <uuid> (id)
Default: "079ba9ad-dcdb-4dda-ba0a-1174dad313c5"
query Parameters
include
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

+

Responses

Response samples

Content type
application/vnd.api+json
{
  • "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": {
        }
      }
    }
}

[Deprecated] Reject Order Deprecated

[Deprecated] Please use the Order Transition endpoint.

+
Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
order
required
string <uuid> (id)
Default: "079ba9ad-dcdb-4dda-ba0a-1174dad313c5"
query Parameters
include
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

+
Request Body schema: application/vnd.api+json
required
object
rejectReason
string [ 1 .. 1000 ] characters

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

+
rejectType
required
string
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"

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.

+

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "order": {
    • "rejectType": "PRODUCT_OUT_OF_STOCK"
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "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": {
        }
      }
    }
}

Product

Options vs Variants

Both, options and variants refer to same concept of having variations of a given product (i.e. Same t-shirt model but different color).

+

Options are deprecated now in favour of variants and no further development will be done on them.

+

Options allow configuring size, color and other type of variations for a product.

+

Variants allow configuring many more parameters, including:

+
    +
  • Custom variation name (i.e. neckline for a t-shirt)
    • +
  • Custom pricing (including discount)
    • +
  • Custom images per variant
    • +
  • ... and many more to come!
    • +
+

Migrating from Options to Variants

In order to start using the new variant system you just need to contact your Ankorstore agent and we will manage everything for you.

+

What will change when migrating to variants?

This is not a breaking change, so endpoints will keep returning information related to options for all the existing orders in our system as well as for all the orders created from the migration onwards.

+

We strongly recommend to start relying on information provided by variants section after the migration will be completed for your brand. Variants will contain information related to new features that won't be supported by the actual options system, so the information provided by options related to your order items may be incomplete.

+

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.

+

List Products

Returns all products

+
Authorizations:
ProductionOAuth2ClientCredentials
query Parameters
page[limit]
integer <int64>

limit the amount of results returned

+
page[before]
string

show items before the provided ID (uuid format)

+
page[after]
string

show items after the provided ID (uuid format)

+
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

+

Responses

Response samples

Content type
application/vnd.api+json
{
  • "meta": {
    • "page": {
      • "from": "123e4567-e89b-12d3-a456-426614174000",
      • "hasMore": true,
      • "perPage": 2,
      • "to": "1ecb023e-7ec0-6d5c-a477-0242ac170008"
      }
    },
  • "jsonapi": {
    • "version": "1.0"
    },
  • "links": {},
  • "data": [
    • {
      • "type": "product",
      • "id": "0c5e6540-0da9-1ecb-bf59-0242ac170007",
      • "attributes": {
        }
      },
    • {
      • "type": "product",
      • "id": "c8466a3c-4fb8-4474-a86f-20f10d14314f",
      • "attributes": {
        }
      }
    ]
}

Get Product

Retrieve a specific product

+
Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
product
required
string <uuid> (id)
Default: "079ba9ad-dcdb-4dda-ba0a-1174dad313c5"
query Parameters
include
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

+

Responses

Response samples

Content type
application/vnd.api+json
{
  • "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,
      • "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": "2171bdc1-fa01-44fa-9342-d99bd1c2befa",
      • "attributes": {
        },
      • "relationships": {
        }
      }
    ]
}

List Product Variants with their stock

Returns all product variants with their stock

+
Authorizations:
ProductionOAuth2ClientCredentials
header Parameters
Accept
string

application/vnd.api+json

+

Responses

Response samples

Content type
application/vnd.api+json
{}

Get product variant with stock

Get product variant with stock

+
Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
productVariant
required
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

+

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "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": {
        }
      }
    },
  • "jsonapi": {
    • "version": "string",
    • "meta": { }
    }
}

Shipping

Ship Order With Custom

Ship using the brands own method

+
Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
order
required
string <uuid> (id)
Default: "079ba9ad-dcdb-4dda-ba0a-1174dad313c5"
query Parameters
include
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

+
Request Body schema: application/vnd.api+json
required
object
required
Array of objects (ShippingLabelParcel) non-empty unique
Array (non-empty)
length
required
integer <= 274
width
required
integer <= 274
height
required
integer <= 274
distanceUnit
required
string (distanceUnit)
Value: "cm"

The unit of distance

+
weight
required
integer [ 1 .. 30000 ]
massUnit
required
string (massUnit)
Value: "g"

The unit of mass

+

Responses

Request samples

Content type
application/vnd.api+json
{
  • "shipping": {
    • "parcels": [
      • {
        },
      • {
        }
      ]
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "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": {
        }
      }
    }
}

List Shipping Quotes

List multiple carrier service quotes that you can choose to ship your order. Please visit our FAQs for more information.

+
Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
order
required
string <uuid> (id)
Default: "079ba9ad-dcdb-4dda-ba0a-1174dad313c5"
query Parameters
include
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

+
Request Body schema: application/vnd.api+json
required
Array of objects [ 1 .. 20 ]
Array
kg
required
number <= 30

The weight of the parcel in kilograms

+
height
required
number <= 274

The height of the parcel in centimeters

+
length
required
number <= 274

The length of the parcel in centimeters

+
width
required
number <= 274

The width of the parcel in centimeters

+
no_dangerous_product
boolean

Indicates if the parcel contains dangerous products

+

Responses

Request samples

Content type
application/vnd.api+json
{
  • "parcels": [
    • {
      • "length": 20,
      • "width": 20,
      • "height": 20,
      • "kg": 21
      }
    ],
  • "no_dangerous_product": true
}

Response samples

Content type
application/vnd.api+json
{
  • "jsonapi": {
    • "version": "1.0"
    },
  • "data": [
    • {
      • "quoteUuid": "1eda3cbb-983b-6a4a-b395-6a0440190584",
      • "carrierCode": "ups",
      • "serviceCode": "11",
      • "serviceCommercialName": "UPS STANDARD",
      • "collectionMethod": [
        ],
      • "shippingCost": {
        }
      }
    ]
}

[Deprecated] Ship Order with Ankorstore Deprecated

[Deprecated] This endpoint is deprecated. We encourage you to use the List Order Quotes endpoint instead.

+
Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
order
required
string <uuid> (id)
Default: "079ba9ad-dcdb-4dda-ba0a-1174dad313c5"
query Parameters
include
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

+
Request Body schema: application/vnd.api+json
required
object
required
Array of objects (ShippingLabelParcel) non-empty unique
Array (non-empty)
length
required
integer <= 274
width
required
integer <= 274
height
required
integer <= 274
distanceUnit
required
string (distanceUnit)
Value: "cm"

The unit of distance

+
weight
required
integer [ 1 .. 30000 ]
massUnit
required
string (massUnit)
Value: "g"

The unit of mass

+

Responses

Request samples

Content type
application/vnd.api+json
{
  • "shipping": {
    • "parcels": [
      • {
        }
      ]
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "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": {
        }
      }
    }
}

Confirm Shipping Quote

Use this endpoint to confirm which quote you want to use to ship your order. +You can confirm either custom or ankorstore quote.

+
Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
quoteId
required
string <uuid> (id)
Default: "079ba9ad-dcdb-4dda-ba0a-1174dad313c5"
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

+
Request Body schema: application/vnd.api+json
labelFormat
string
Default: "default"
Enum: "full_page" "default"

This field is not required. If you don't' define it we will use the default label format as well.

+
object or object
One of
trackingProvider
required
string

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
required
string

The tracking number (may contain characters as well)

+

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "labelFormat": "default"
}

Response samples

Content type
application/vnd.api+json
Example
{
  • "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"
    }
}

[Deprecated] Confirm Order Shipping Deprecated

[Deprecated] Please use the Confirm Shipping Quote endpoint.

+
Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
order
required
string <uuid> (id)
Default: "079ba9ad-dcdb-4dda-ba0a-1174dad313c5"
query Parameters
include
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

+
Request Body schema: application/vnd.api+json
object or object
One of
trackingProvider
required
string

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
required
string

The tracking number (may contain characters as well)

+

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "order": {
    • "trackingProvider": "ups",
    • "trackingNumber": "123456"
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "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": {
        }
      }
    }
}

Schedule Pickup for order

Use this endpoint for scheduling a pickup for the order

+
Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
order
required
string <uuid> (id)
Default: "079ba9ad-dcdb-4dda-ba0a-1174dad313c5"
query Parameters
include
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

+
Request Body schema: application/vnd.api+json
object
One of
pickupDate
required
string

Requested date for the pickup

+
pickupTime
required
string

Time period for the pickup (9-15 or 11-17)

+
pickupAddress
required
object

Address for the pickup

+

Responses

Request samples

Content type
application/vnd.api+json
{
  • "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"
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "jsonapi": {
    • "version": "1.0"
    },
  • "data": {
    • "type": "order",
    • "id": "1ecb023e-7ec0-6d5c-a477-0242ac170007",
    • "attributes": {
      • "status": "shipped",
      • "reference": 3434273911,
      • "brandCurrency": "EUR",
      • "brandTotalAmount": 12588,
      • "brandTotalAmountVat": 693,
      • "brandTotalAmountWithVat": 13281,
      • "shippingMethod": "ankorstore",
      • "shippingOverview": {},
      • "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": {
        }
      }
    },
  • "included": [
    • {
      • "type": "retailer",
      • "id": "092b63ce-c5b9-1eca-b05f-0242ac170007",
      • "attributes": {
        }
      }
    ]
}

Stock Management

Product 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

+
{
+  "data": {
+    "type": "productVariants",
+    "id": "1ed18988-6651-610e-8223-aa5cd9844f96",
+    "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

+
{
+  "data": {
+    "type": "productVariants",
+    "id": "1ed18988-6651-610e-8223-aa5cd9844f96",
+    "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

+
{
+  "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

+

Update product variant stock

Update product variant stock

+
Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
productVariant
required
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

+
Request Body schema: application/vnd.api+json
required
ProductVariantStockUpdateSetStockQuantity (object) or ProductVariantStockUpdateSetIsAlwaysInStockRequest (object)
Any of
id
required
type
required
string (type)
required
object
stockQuantity
required
number >= 0

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "type": "product-variants",
    • "id": "2171bdc1-fa01-44fa-9342-d99bd1c2befa",
    • "attributes": {
      • "isAlwaysInStock": false,
      • "stockQuantity": 20
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "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": {
        }
      }
    },
  • "jsonapi": {
    • "version": "string",
    • "meta": { }
    }
}

Bulk Operations

Multiple operations on different resources by a single request

+
Authorizations:
ProductionOAuth2ClientCredentials
Request Body schema: application/vnd.api+json
required
Array of objects [ 1 .. 50 ] items
Array ([ 1 .. 50 ] items)
op
required
string
Value: "update"
required
ProductVariantStockUpdateSetIsAlwaysInStockRequest (object) or ProductVariantStockUpdateSetStockQuantity (object)
Any of
id
required
type
required
string (type)
required
object
isAlwaysInStock
required
boolean

Whether the current product variant is always in stock

+

Responses

Request samples

Content type
application/vnd.api+json
No sample

Response samples

Content type
application/vnd.api+json
{
  • "atomic:results": [
    • {
      • "data": {
        }
      }
    ]
}

Testing

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.

+

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.

+

Create Test Order (Sandbox Only)

Creates a test order ready to be confirmed based on the options provided. ONLY AVAILABLE IN SANDBOX.

+
Authorizations:
ProductionOAuth2ClientCredentials
query Parameters
include
header Parameters
Accept
string

application/vnd.api+json

+
Content-Type
string

application/vnd.api+json

+
Request Body schema: application/vnd.api+json

The options that can be provided when creating a test order

+
retailerId
string or null

The Retailer Id

+
itemQuantity
integer or null [ 1 .. 999 ]

If productVariants/productOptions are not provided, then this will set the quantity each order item created.

+
Array of objects or null unique

List of variant IDs and their quantities. Cannot be included with productOptions.

+
Array
id
itemQuantity
integer [ 1 .. 999 ]
Array of objects or null unique

List of option IDs and their quantities - Only use if you are currently using the old options system. Cannot be included with productVariants

+
Array
id
itemQuantity
integer [ 1 .. 999 ]

Responses

Request samples

Content type
application/vnd.api+json
Example
{
  • "retailerId": "5ee4d438-0489-4634-aa60-746f485af458"
}

Response samples

Content type
application/vnd.api+json
{
  • "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": {
        }
      }
    }
}

User

Configuration for the current user

Returns configuration for the current user

+
Authorizations:
ProductionOAuth2ClientCredentials
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

+

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "type": "string",
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "attributes": {
      • "currency": "string",
      • "country": "string",
      • "browserId": "string"
      },
    • "required": null
    },
  • "jsonapi": {
    • "version": "string",
    • "meta": { }
    }
}

Configuration for the specified user

Returns configuration of the specified user

+
Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
id
required
string <uuid>

User ID

+
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

+

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "type": "string",
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "attributes": {
      • "currency": "string",
      • "country": "string",
      • "browserId": "string"
      },
    • "required": null
    },
  • "jsonapi": {
    • "version": "string",
    • "meta": { }
    }
}
+ + + +