From 494c131b98ed7bc8e6644366f959296beb126acb Mon Sep 17 00:00:00 2001 From: roman-kovalev-aks Date: Mon, 18 Dec 2023 08:40:14 +0000 Subject: [PATCH] =?UTF-8?q?Deploying=20to=20main=20from=20@=20ankorstore/a?= =?UTF-8?q?nkorstore@975990d900e58f1a7b02890af2352da314aba6d1=20?= =?UTF-8?q?=F0=9F=9A=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- pull/37555/index.html | 3878 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 3878 insertions(+) create mode 100644 pull/37555/index.html diff --git a/pull/37555/index.html b/pull/37555/index.html new file mode 100644 index 0000000..4caa31f --- /dev/null +++ b/pull/37555/index.html @@ -0,0 +1,3878 @@ + + + + + + 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

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/

+
+
Ankorstore API Specification

How to work with API

ℹ️ 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 which is based +on the JSON:API 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

+

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

+

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

+

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

🔗 Learn more about JSON:API 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

+

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 API 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<...>"
+}
+
+

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<...>"
+  },
+  "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.

+

Available APIs

ℹ️ Following groups of endpoints are available in the current version of the API:

+
    +
  • General - endpoints related to the general information and actions on the platform.
    • +
  • User - endpoints related to the user management.
    • +
  • Catalog - endpoints related to the catalog management.
    • +
  • Ordering - endpoints related to the order management.
    • +
  • Shipping - endpoints related to the shipping.
    • +
  • Fulfillment - endpoints related to the fulfillment.
    • +
  • Testing - helper endpoints for testing and data generation.
    • +
+

Webhook Subscription

ℹ️ Ankorstore provides a mechanism of webhook notifications to notify you of events that happen on the platform.

+
+ +

Please note, that webhook notifications are only available for Internal Orders. +The possibility to subscribe to the External Orders events will be added soon.

+
+ +

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.

+

Testing API

ℹ️ 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

+
+ +

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.

+

General

ℹ️ This section contains different general endpoints, mostly transversal for the whole system.

+

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

User

ℹ️ This section describes the API endpoints which can be used for managing user-related resources.

+

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

Catalog

ℹ️ 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

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

+

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

Returns all product variants with their stock

+
Authorizations:
ProductionOAuth2ClientCredentials
query Parameters
filter[sku]
Array of strings
Example: filter[sku]=MY-SKU12,MY-SKU34

Filter by SKU(s)

+
header Parameters
Accept
string

application/vnd.api+json

+

Responses

Response samples

Content type
application/vnd.api+json
{}

Get Product Variant

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

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

Ordering

ℹ️ 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,

+
[GET] /api/v1/master-orders
+
+

the response will contain only a list of identifiers without any wrapped orders:

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

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

+

💡 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 deprecated

+

Please note, that we have fully completed migrating our system to the new product model with product options completely +replaced by product variant. It means, the usage of product options is not deprecated and will be removed in the future +versions of the API.

+

Please, consider updating your API clients in a favor of using orderItems.productVariant instead of orderItems.productOption +to avoid any issues in the future.

+
+ +

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:

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

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

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

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

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

+

Available operations on Internal Orders

+ +

You can also find some details about shipping in the dedicated 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 +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. +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. +
  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. +
  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").
    4. +
+

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 +and Fulfillment API.

+

A practical example

+
+ +

The assumption here is that you already authenticated and able to access the API. +If not, please follow the 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:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldValue
Client nameJohn Doe
Company nameACME
Phone+33 612345678
Emailjohn@acme.com
Address123, Rue de Foo Bar, Paris, 75001, France
+

with the following content:

+ + + + + + + + + + + + + + + +
Product SKUQuantity
AB-123412
CD-00-XY5
+

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

+
[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 SKUQuantityFulfillable ID
AB-1234121ac37dbf-f25d-4c0c-bcc8-ad8af946b541
CD-00-XY5e5e91243-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. +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,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. +
  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.
    3. +
+

After these simply calculations, you should end up with the following information:

+ + + + + + + + + + + + + + + + + + + + + +
Product SKUQuantityFulfillable IDBatch Size
AB-1234121ac37dbf-f25d-4c0c-bcc8-ad8af946b5413
CD-00-XY5e5e91243-d11a-47a3-9308-22af70da5bc45
+

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:

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

+

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

+

List Master Orders

Retrieve a list of Master Orders

+
Authorizations:
ProductionOAuth2ClientCredentials
query Parameters
include
string
Enum: "internalOrder" "externalOrder" "shipment"
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
{
  • "data": [
    • {
      • "type": "string",
      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "relationships": {
        }
      }
    ],
  • "included": [
    • {
      • "type": "string",
      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "attributes": {
        },
      • "relationships": {
        }
      }
    ]
}

Get Master Order

Retrieve a specific Master Order

+
Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
master_order
required
query Parameters
include
string
Enum: "internalOrder" "externalOrder" "shipment"
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",
    • "relationships": {
      • "internalOrder": {
        },
      • "externalOrder": {
        },
      • "shipment": {
        }
      }
    },
  • "included": [
    • {
      • "type": "string",
      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "attributes": {
        },
      • "relationships": {
        }
      }
    ]
}

List Internal Orders

Retrieve a list of Internal Orders

+
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 Internal Order

Retrieve a specific order

+
Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
order
required
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 Internal 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
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": {
        }
      }
    }
}

Create External Order

Creates a new External Order

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

application/vnd.api+json

+
Request Body schema: application/json
required
required
object

Shipping address of the recipient.

+
country
required
string^[A-Z]{2}$

ISO 3166-1 country code.

+
postalCode
required
string

Valid postal code, matching the country.

+
city
required
string [ 1 .. 255 ] characters

Name of the destination city.

+
street
required
string [ 1 .. 60 ] characters

Street address, should not exceed the maximum length +in order to fit the dedicated place on the shipping label.

+
company
required
string <= 70 characters

Name of the company

+
firstName
required
string [ 1 .. 64 ] characters

First name of the person, receiving the order

+
lastName
required
string [ 1 .. 64 ] characters

Last name of the person, receiving the order

+
phone
required
string non-empty

Phone number of the person, receiving the order. The format match the country.

+
email
required
string <email>

Email of the person, receiving the order

+
required
Array of objects

List of fulfillable items with their corresponding quantities.

+
Array
fulfillableId
required
string <uuid>

Fulfillable identifier, find more about it here.

+
quantity
required
integer

Quantity of the fulfillable item in units.

+
masterOrderUuid
string <uuid>

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
string

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.

+

Responses

Request samples

Content type
application/json
{
  • "shippingAddress": {
    • "country": "string",
    • "postalCode": "string",
    • "city": "string",
    • "street": "string",
    • "company": "string",
    • "firstName": "string",
    • "lastName": "string",
    • "phone": "string",
    • "email": "user@example.com"
    },
  • "items": [
    • {
      • "fulfillableId": "611a6658-a5d5-475f-8280-4b693104739b",
      • "quantity": 0
      }
    ],
  • "masterOrderUuid": "8f6deb2e-3f81-488c-8887-508b733f0a5b",
  • "customReference": "string"
}

Response samples

Content type
application/vnd.api+json
{
  • "jsonapi": {
    • "version": "string",
    • "meta": { }
    },
  • "data": null
}

Shipping

ℹ️ 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 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.

+
+ +

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.

+

⚠️ 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.

+

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
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": {
        }
      }
    ]
}

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
quote
required
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"
    }
}

Schedule Pickup for order

Use this endpoint for scheduling a pickup for the order

+
Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
order
required
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": {
        }
      }
    ]
}

Ship Order With Custom

Ship Internal Order using the brands own method

+
Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
order
required
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": {
        }
      }
    }
}

Fulfillment

ℹ️ 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

+

Get Fulfillment Order

Returns details of a single fulfillment order

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

Fulfillment order 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": {
      • "reference": "string",
      • "status": "internal",
      • "createdAt": "2019-08-24T14:15:22Z",
      • "items": [
        ]
      },
    • "links": {
      • "order": "string"
      },
    • "relationships": {
      • "statusUpdates": {
        }
      }
    },
  • "jsonapi": {
    • "version": "string",
    • "meta": { }
    },
  • "included": [
    • {
      • "type": "string",
      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "attributes": {
        }
      }
    ]
}

List Fulfillables

Returns a list of fulfillables with their stock availability

+
Authorizations:
ProductionOAuth2ClientCredentials
query Parameters
fulfillableIds[]
required
Array of strings <uuid> non-empty [ items <uuid > ]

A set of UUIDs representing the fulfillables to check availability for

+
header Parameters
Accept
string

application/vnd.api+json

+

Responses

Response samples

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

Testing

ℹ️ 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.

+

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

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

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

Deprecated

ℹ️ 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:

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

+

[Ordering] Accept Order Deprecated

[Deprecated] Please use the Order Transition endpoint.

+
Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
order
required
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": {
        }
      }
    }
}

[Ordering] Reject Order Deprecated

[Deprecated] Please use the Order Transition endpoint.

+
Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
order
required
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": {
        }
      }
    }
}

[Shipping] 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
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": {
        }
      }
    }
}

[Shipping] Confirm Order Shipping Deprecated

[Deprecated] Please use the Confirm Shipping Quote endpoint.

+
Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
order
required
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": {
        }
      }
    }
}
+ + + +