From d53176eea05191b7ff1f33662aae609b476203cb Mon Sep 17 00:00:00 2001 From: villfa Date: Fri, 13 Dec 2024 13:40:23 +0000 Subject: [PATCH] =?UTF-8?q?Deploying=20to=20main=20from=20@=20ankorstore/a?= =?UTF-8?q?nkorstore@bce503762e792e6b5e43611402f73d86cd93d81c=20?= =?UTF-8?q?=F0=9F=9A=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- pull/45835/index.html | 5623 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 5623 insertions(+) create mode 100644 pull/45835/index.html diff --git a/pull/45835/index.html b/pull/45835/index.html new file mode 100644 index 0000000..a7f26ac --- /dev/null +++ b/pull/45835/index.html @@ -0,0 +1,5623 @@ + + + + + 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.

+

Subscribing

+

There are two ways to manage your webhook subscription on the platform:

+
    +
  1. Via UI in your Ankorstore account. You can find this functionality in the Private Apps tab of the Integrations section.
    2. +
  2. Directly via API. Find more details in the dedicated Webhoooks section of API specification.
    3. +
+

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
    • +
  • external_order.created - A new external order is created for the brand
    • +
  • external_order.awaiting_fulfillment - Order is waiting for fulfillment
    • +
  • external_order.cancelled - Order is cancelled
    • +
  • external_order.shipped - Order shipped from the warehouse
    • +
  • external_order.arrived - Order is arrived and completed
    • +
+

Note: When External Order is created webhook external_order.created is fired and at same time fulfillment is requested +which means external_order.awaiting_fulfillment is also fired. Due to async nature of webhook when you receive +these webhooks most likely order status is awaiting_fulfillment for external_order.created webhook too.

+

Signature

+

Our webhooks provide a signature so you can verify the payload hasn't been tampered with. +This signature can be found on the header signature.

+

This is how the signature is calculated:

+
/**
+ * @var string $payload JSON payload of the received webhook
+ * @var string $secret Secret key which can be found in the particular webhook subscription settings
+ * @var string $signature Calculated signature, to be compared with the value in the request header
+ */
+$signature = hash_hmac('sha256', $payload, $secret);
+
+

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

+

Note: the secret key needed for verification webhook signature is not the same as the API secret key. +Each webhook subscription has its own secret key which can be found in the particular webhook subscription settings.

+

Retries

+

If the response status code is not a 2xx then we will retry the webhook for 5 attempts with an exponential backoff.

+

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.

+

Fair Use Statement

Ankorstore provides access to its API (Application Programming Interface) for the purpose of enabling brands to integrate with our services to ease their workflow. We encourage the use of our API in accordance with the following fair use principles:

+
    +

  1. Respect for Rate Limits: To ensure fair access for all users, we enforce rate limits on API requests. Developers are encouraged to adhere to these limits and implement appropriate strategies, such as utilising webhooks, caching, etc. to minimize unnecessary requests and reduce load on our servers.

    +
    2. +

  2. Data Integrity and Privacy: Developers must handle any data obtained through our API with care, respecting user privacy and maintaining data integrity. Any misuse or unauthorized access to user data is strictly prohibited and may result in termination of API access.

    +
    3. +

  3. Compliance with Terms of Service: All usage of our API is subject to our Terms of Service. Developers are expected to review and comply with these terms, which outline the rights and responsibilities associated with using our API.

    +
    4. +
+

By accessing or using our API, you agree to abide by these fair use principles and any additional terms and conditions specified in our documentation or Terms of Service. Ankorstore reserves the right to monitor API usage and take appropriate action to enforce these guidelines, including limiting or revoking access to the API for users who violate them.

+

For questions or concerns regarding API usage or these fair use principles, please contact Ankorstore Support.

+

Applications

List Applications

List existing application for the current authenticated user

+
Authorizations:
ProductionOAuth2ClientCredentials
header Parameters
Accept
string

application/vnd.api+json

+

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "43efbfbd-bfbd-1eef-1e6a-6200efbfbdef",
    • "type": "application",
    • "attributes": {
      • "name": "My sandbox",
      • "developerEmail": "dev@my-app.com",
      • "clientId": "k322k7frs87e8w7hri3jkke7ry7",
      • "clientSecret": null
      }
    },
  • "included": [
    • {
      • "type": "string",
      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "attributes": {}
      }
    ],
  • "jsonapi": {
    • "version": "string",
    • "meta": { }
    }
}

Brands

Get own brand details

Get own brand details

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

application/vnd.api+json

+

Responses

Response samples

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

Get Retailer relation

Returns brand retailer relation

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

Ankorstore retailer UUID

+
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": {
      • "automaticOrderValidationMode": true
      }
    },
  • "jsonapi": {
    • "version": "string",
    • "meta": { }
    }
}

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"
      }
    },
  • "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"
      }
    },
  • "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": {
+    "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": {
+    "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>
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,
      • "productTypeId": 1,
      • "active": true,
      • "outOfStock": false,
      • "archived": false,
      • "retailPrice": 750,
      • "wholesalePrice": 426,
      • "originalWholesalePrice": 426,
      • "createdAt": "2020-08-27T14:26:38.000000Z",
      • "indexedAt": "2022-02-10T03:26:11.000000Z",
      • "updatedAt": "2022-02-09T14:49:09.000000Z",
      • "images": [],
      • "tags": [
        ]
      }
    },
  • "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,
      • "fulfillableId": "8f066352-67cb-1efa-bddb-9e3047198b2e",
      • "availableAt": "2028-01-01T00:00:00.000000Z",
      • "images": []
      },
    • "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
object
Any of
id
required
type
required
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,
      • "fulfillableId": "8f066352-67cb-1efa-bddb-9e3047198b2e",
      • "availableAt": "2028-01-01T00:00:00.000000Z",
      • "images": []
      },
    • "relationships": {
      • "product": {
        }
      }
    },
  • "jsonapi": {
    • "version": "string",
    • "meta": { }
    }
}

Catalog Integrations

👋 Getting Started

The catalogue integration process relies on the concept of operations. An operation is a batch of records +representing the products to create, update or delete. The completion state of an operation depends +on the execution result for every record it contains. It means an operation might fail without necessarily +stopping or marking the whole operation as failed (this particular state is defined as “Partially failed”).

+
    +
  • Operations can be of type import, update or delete.
    • +
  • Only one open operation (not yet started) is allowed at a time.
    • +
  • Only one operation can be performed (started) at a time.
      +
    • Any subsequent operation will be queued with status pending until previous one has finished processing.
      • +
    • If no previous operation is being processed, operation will start processing right away.
      • +
    +
    • +
+

Operation Statuses

+

The status attribute represents the current state of the operation, below is a table that describes each state:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
StatusDescription
createdThe operation was created and not yet started. At this stage, the operation is considered open and products can still be added to the batch.
skippedThe operation is empty and was skipped (No action required). When an operation is skipped, an empty report is generated and the callback URL is called to notify operation is completed.
startedThe operation started and is processing.
pendingOperation is waiting for its turn on the processing queue. The operation could not be started because another one was being processed.
succeededAll products were successfully processed.
failedAll products failed to be processed.
partially_failedNot all products were successfully processed.
+

💡 Operation workflow

The complete workflow for an operation occurs in 3 stages: operation creation, operation processing and reporting. +The following diagram illustrates these stages and how they are chained.

+
+%%{init: {"flowchart": {"curve":"basis", "htmlLabels":false, "diagramPadding":24 } } }%%
+graph LR
+
+created("Operation Created")
+start("Start Processing")
+started("Processing\nStarted")
+succeeded(Succeeded):::success
+skipped("Processing Skipped"):::success
+pending("Operation pending")
+failed(Failed):::failure
+partial(Partially Failed):::warning
+report("Report\nGenerated")
+notified(Callback Sent)
+
+subgraph creating[Creating Operation]
+created -- Add Products --> created
+end
+
+created -- Start Operation --> Start{?}
+Start -->|"Another Operation execution in progress"| pending
+Start --->|"No other Operation in progress"| start --> E{?}
+E -->|"Batch.size > 0"| processing
+E --->|"Batch is empty"| skipped
+
+subgraph processing[Processing Operation]
+direction LR
+started --> succeeded
+started --> partial
+started --> failed
+end
+
+succeeded --> operationCompletedActions
+partial --> operationCompletedActions
+failed --> operationCompletedActions
+
+subgraph reporting[Reporting]
+report -- Notify --> notified
+end
+
+subgraph triggerNext[Trigger next pending Operation]
+end
+
+subgraph operationCompletedActions[Post-Complete Operation Actions]
+reporting
+triggerNext
+end
+
+pending -- Wait for previous Operation to finish execution --> start
+
+skipped -- Generate empty report --> operationCompletedActions
+
+classDef default stroke:#4b475f,stroke-width:1px,fill:#ffffff,color:#4b475f
+classDef success stroke:#1aae9f,stroke-width:1px,fill:#cfeeeb,color:#293845
+classDef failure stroke:#d3455b,stroke-width:1px,fill:#f6d8dd,color:#293845
+classDef warning stroke:#f7c325,stroke-width:1px,fill:#fdf2d1,color:#293845
+linkStyle default stroke:#788896,stroke-width:1px,fill:transparent
+
+ +

Creating an Operation

+

The full flow of creating a complete operation consists in two steps:

+

1. Create a new operation

+

Send a POST request to /api/v1/catalog/integrations/operations

+

Example request:

+
{
+    "data": {
+        "type": "catalog-integration-operation",
+        "attributes": {
+            "source": "shopify",
+            "callbackUrl": "https://callback.url/called/after/processing",
+            "operationType": "import"
+        }
+    }
+}
+
+
    +
  • At this point the new operation has been created and waiting to receive products data
    • +
  • Operation ID will be returned in the response payload
    • +
+

2. Add product data to operation

+

Send a POST request to /api/v1/catalog/integrations/operations/{operationId}/products

+

Products can be added only to operations with status created.

+

If operation has been started already (having any of started, pending, skipped, succeeded, partially_failed, failed, cancelled status), +the request will fail with a 403 Forbidden status code.

+

Example request:

+
{
+    "products": [
+        {
+            "id": "B006GWO5WK",
+            "type": "catalog-integration-product",
+            "attributes": {
+                "external_id": "B006GWO5WK",
+                "name": "Example product"
+                // ...
+            }
+        }
+    ]
+}
+
+

You can perform as many requests as needed to append product data during this stage.

+

Operation Processing

+

In order to start processing the operation, you have to send a PATCH request +to /api/v1/catalog/integrations/operations/{operationId} with the expected operation status (i.e. “started”).

+

If there is any other operation being executed at that time, the operation will be enqueued to be processed +with the status pending and will be started as soon as it gets a free slot in the queue. Otherwise, the +operation will be started right away.

+

Example request:

+
{
+    "data": {
+        "id": "90567710-de47-49e4-8536-aab80c1a469c",
+        "type": "catalog-integration-operation",
+        "attributes": {
+            "status": "started"
+        }
+    }
+}
+
+

Execution Report

+

When an operation completes, an execution report is generated. +It provides the execution results (success or failure) for every product of the operation.

+

You can access this report by reading from the following endpoint.

+
GET /api/v1/catalog/integrations/operations/{operationId}/results
+
+

💡 Event Callbacks

Callbacks enable you to get notified when events occur in the operation process. For example, you can +configure a callback to notify you when the operation is completed. The notification is sent via +an HTTP request to the URL you specify in the operation settings.

+

Callbacks can be used to trigger automated actions in your integration.

+

Supported events

+

You can find here below the complete list of all the topics {{resource}}.{{event}} you can monitor:

+ + + + + + + + + + + + + + + +
TopicTrigger
catalog-integration-operation.completedAn operation reaches a completed state such as Success, Failed, or Partially Failed
catalog-integration-operation.cancelledAn operation was cancelled. This event is triggered when an operation processing is Skipped (i.e. the operation batch is empty and no action is required).
+

Event schema

+

A callback event is represented as a JSON object and has the following properties:

+
    +
  • event — the name of the event that occurred (e.g. “completed”)
    • +
  • topic — the event category represented as a unique identifier of the event type. +The topic is defined as a concatenation of the resource and event names {$.data.type}.{$.event}, +e.g. “catalog-integration-operation.completed”. You might use this topic as a partition key to distribute +the callback events you receive to separate queues or pools of workers to process the callbacks asynchronously.
    • +
  • occurredAt — the date and time when the event occurred
    • +
  • data — the JSON:API resource describing the state of the entity which triggered the callback
    • +
+

A callback event is delivered as a POST request to your endpoint. The following payload represents the notification +request that is triggered when an operation successfully completes:

+
{
+    "event": "completed",
+    "topic": "catalog-integration-operation.completed",
+    "occurredAt": "2024-03-21T13:42:54+00:00",
+    "data": {
+        "id": "90567710-de47-49e4-8536-aab80c1a469c",
+        "type": "catalog-integration-operation",
+        "attributes": {
+            // ...
+            "status": "succeeded",
+            "createdAt": "2024-03-21T13:13:03+00:00",
+            "startedAt": "2024-03-21T13:19:32+00:00",
+            "completedAt": "2024-03-21T13:42:54+00:00"
+            // ...
+        }
+    }
+}
+
+

Handling callbacks

+

The endpoint listening for callbacks has 3 seconds to respond with a 2xx (usually 200) +response code, acknowledging a successful delivery. If the request times out or gets a response +with a status code other than 2xx, it is considered failed.

+
+ +

Handling webhook failures

+

If a callback fails (whatever the reason) no further calls to the related endpoint are made.

+
+ +

Testing callback

+

A number of websites, such as https://webhook.site and https://requestbin.com, provide free URLs that +can be used to test callbacks. Simply create a URL on one of these sites, then configure your webhook +to use it. These sites allow you to see the details of the request sent to them by the callback service.

+

In addition, the Ngrok service (https://ngrok.com) allows you to tunnel callback requests to a non-publicly +accessible server, enabling you to test your callback-handling code before making it public.

+

Operations and Drafts behaviour

+ + + + + + + + + + + + + + + + + + + +
TypeBehaviour
importWhen executing an import operation existing drafts will be cleaned and new ones will be created if any of the products attached to the operation has any validation issue.
updateWill not have any impact on existing drafts.
deleteWill not have any impact on existing drafts.
+

Create a new operation

Create new Operation to process over related Catalog Integration

+
+

ID of the operation will be returned on the response payload. + This ID should be used to add products data through POST /catalog/integrations/operations/{ID}

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

application/vnd.api+json

+
Request Body schema: application/vnd.api+json
object
type
string
Allowed value: "catalog-integration-operation"

The type of resource to create

+
object

The operation attributes

+
source
required
string (OperationSource)
Allowed values: "shopify" "woocommerce" "prestashop" "other"

Source of the operation

+
callbackUrl
required
string

The url of the endpoint that will be called when an operation completes. When an operation reaches a completed state such as Success, Failed, or Partially Failed the API platform will trigger a request to your endpoint.

+
operationType
required
string (OperationType)
Allowed values: "import" "update" "delete"

Operation type

+
updateFields
Array of strings
Items Allowed values: "stock" "prices" "description" "dimensions" "images" "name" "prices" "product_type_id" "retail_price" "stock" "tags" "unit_multiplier" "vat_rate" "wholesale_price"

Optional list of fields that will be taken into account when updating the products provided. This list will be +only taken into account for operations of type update.

+
    +
  • For sources shopify, woocommerce and prestashop: If list is not provided or empty, all stock +and prices related fields will be updated
    • +
  • For source other: If list is not provided or empty, all fields will be updated
    • +
+

Group fields:

+
    +
  • If stock is provided, both stock_quantity and is_always_in_stock properties will be updated
    • +
  • If prices is provided, both wholesale_price and retail_price will be updated
    • +
+

Responses

Callbacks

Request samples

Content type
application/vnd.api+json
Example
{}

Response samples

Content type
application/vnd.api+json
Example
{}

Callback payload samples

Callback
POST: A callback triggered when events occur in the operation process
Content type
application/json
{
  • "event": "completed",
  • "topic": "catalog-integration-operation.completed",
  • "occurredAt": "2019-08-24T14:15:22Z",
  • "data": {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "type": "catalog-integration-operation",
    • "attributes": {
      • "source": "shopify",
      • "status": "created",
      • "operationType": "import",
      • "updateFields": [
        ],
      • "createdAt": "2019-08-24T14:15:22Z",
      • "startedAt": null,
      • "completedAt": null,
      • "callbackUrl": null,
      • "totalProductsCount": 0,
      • "processedProductsCount": 0,
      • "failedProductsCount": 0
      }
    }
}

Create a deletion operation

Creates an Operation that deletes products from Ankorstore's catalog. The operation is started directly after creation.

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

application/vnd.api+json

+
Request Body schema: application/vnd.api+json
source
required
string (OperationSource)
Allowed values: "shopify" "woocommerce" "prestashop" "other"

Source of the operation

+
callbackUrl
required
string

The url of the endpoint that will be called when an operation completes. When an operation reaches a completed state such as Success, Failed, or Partially Failed the API platform will trigger a request to your endpoint.

+
required
Array of objects
Array
type
string
Allowed value: "catalog-integration-product"

The type of resource to create

+
object
external_id
string

The external identifier of the product to delete

+
Array of objects
Array
sku
string

The SKU of the product variant to delete

+

Responses

Callbacks

Request samples

Content type
application/vnd.api+json
{
  • "source": "shopify",
  • "callbackUrl": "https://callback.url/called/after/processing",
  • "products": [
    • {
      • "type": "catalog-integration-product",
      • "attributes": {
        }
      }
    ]
}

Response samples

Content type
application/vnd.api+json
{}

Callback payload samples

Callback
POST: A callback triggered when events occur in the operation process
Content type
application/json
{
  • "event": "completed",
  • "topic": "catalog-integration-operation.completed",
  • "occurredAt": "2019-08-24T14:15:22Z",
  • "data": {
    • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    • "type": "catalog-integration-operation",
    • "attributes": {
      • "source": "shopify",
      • "status": "created",
      • "operationType": "import",
      • "updateFields": [
        ],
      • "createdAt": "2019-08-24T14:15:22Z",
      • "startedAt": null,
      • "completedAt": null,
      • "callbackUrl": null,
      • "totalProductsCount": 0,
      • "processedProductsCount": 0,
      • "failedProductsCount": 0
      }
    }
}

Retrieve an operation

Returns specific Operation resource data

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

The unique identifier of the operation

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

application/vnd.api+json

+

Responses

Response samples

Content type
application/vnd.api+json
Example
{}

Patch Operation resource

Patch Operation resource

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

The unique identifier of the operation

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

application/vnd.api+json

+
Request Body schema: application/vnd.api+json
object
id
string <uuid>

The unique identifier of the operation to update

+
type
string
Allowed value: "catalog-integration-operation"

The type of resource to be updated

+
object
status
string
Allowed value: "started"

The operation status. Set this attribute to started in order to start processing the operation. Please note that an attempt to start processing an empty operation (i.e. an operation with no products attached) always leads to the operation being marked as "Skipped" and triggers the generation of an empty report. +Only one Operation is allowed to be started at a time. Any attempt of starting an Operation while another one is currently being processed (started, but not completed/cancelled yet) will result on a pending status. +Once an Operation processing has been completed, next pending one for the Brand will be executed automatically.

+

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "90567710-de47-49e4-8536-aab80c1a469c",
    • "type": "catalog-integration-operation",
    • "attributes": {
      • "status": "started"
      }
    }
}

Response samples

Content type
application/vnd.api+json
Example
{}

Add products to an operation

Add products data to an existing Operation resource

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

The unique identifier of the operation

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

application/vnd.api+json

+
Request Body schema: application/vnd.api+json
Array of objects
Array
id
required
string

User-defined unique identifier of the product

+
type
required
string
Default: "catalog-integration-product"

Type of resource

+
object

The product attributes. In case of a deletion operation, no attribute is expected. The only required information is the unique product identifier to delete (see following example).

+
 {
+    "id": "<User-defined Identifier>",
+    "type": "catalog-integration-product"
+ }
+
+
external_id
string

ID from external source

+
name
string

Product name

+
tags
Array of any

List of product tags

+
main_image
string

URL of the image that will be used as main one for the product

+
+

It will have the number 1 order

+
+
Array of objects

List of additional images for the product (Variants will inherit them)

+
Array
order
integer

Order number for the image to be shown

+
+

Product Images: +1 belongs to main image +Additional ones need to use 2 onwards

+
+
+

Variant Images: +Will inherit from parent product if not provided +Will be shown in the provided order

+
+
url
string

URL of the image

+
hs_code
string

HS code

+
currency
string
Allowed values: "GBP" "EUR" "SEK"

Currency used in pricing

+
vat_rate
number <float>

VAT rate

+
description
string

Product description

+
+

Must be at least 30 chars long

+
+
discount_rate
number <float>

Discount rate applied

+
+

Must be between 0 and 100

+
+
unit_multiplier
number <integer>

The minimum quantity in which a product is sold. When adding the product on the cart, cart price is computed by multiplying wholesale price * unit_multiplier

+
+

Must be at least 1

+
+
ankorstore_product_type_id
number <integer>

ID for Product Type as defined on Ankorstore taxonomy. When present it will be treated as truth and external_product_type_id will be kept as reference. For more information on available product types see Ankorstore Taxonomy

+
external_product_type_id
string

ID for Product Type as defined on the external source. When ankorstore_product_type_id is not present this will be tread as fallback to try and match the taxonomy from external source to Ankorstore taxonomy. This is not guaranteed, it is advised to always share directly the ankorstore_product_type_id to ensure product created will be contain the expected product type as desired and external_product_type_id kept as reference.

+
Array of objects

Attributes of the product type

+
Array
Any of
name
string
Allowed value: "age_group"

Age group

+
value
string
Allowed values: "baby" "kids" "adult"

Age group

+
wholesale_price
number <float>

Wholesale price

+
retail_price
number <float>

Retail price

+
made_in_country
string

Country code in Alpha-2 format

+
object

Shape properties of the item

+
object

Item dimensions

+
object

Item capacity

+
object

Item weight

+
Array of objects

Variant of the product

+
+

Every product must have at least one variant > In the case of multiple variants, unique options should be provided for each of them

+
+
Array
ian
string

IAN code

+
+

Must be exactly 13 chars long

+
+
sku
string

SKU code

+
stock_quantity
integer

Stock available, 0 means out of stock

+
is_always_in_stock
boolean

If the product is always in stock, we will ignore the stock value

+
external_id
string

ID for the variant from external source

+
discount_rate
number <float>

Discount rate applied

+
+

Must be between 0 and 100 > Will be inherited from parent Product if not provided

+
+
retail_price
number <float>

Retail price

+
+

Will be inherited from parent Product if not provided

+
+
wholesale_price
number <float>

Wholesale price

+
+

Will be inherited from parent Product if not provided

+
+
object

Shape properties of the item

+
Array of objects

Options specific to the variant

+
Array of objects

Images related to specific variant. Will be shown after the ones inherited from parent product in the provided order.

+

Responses

Request samples

Content type
application/vnd.api+json
{
  • "products": [
    • {
      • "id": "a12aef05-7c20-4efb-a336-ea53be904d0e",
      • "type": "catalog-integration-product",
      • "attributes": {
        }
      }
    ]
}

Response samples

Content type
application/vnd.api+json
{
  • "jsonapi": {
    • "version": "1.0"
    },
  • "meta": {
    • "totalProductsCount": 104
    }
}

Retrieve an operation report

Once an operation is completed, an execution report is generated. This report summarises the result of the operation execution for each of its products.

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

The unique identifier of the operation

+
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": "29c60b89-0fb6-4bd9-9c1e-2d312cf141e3",
      • "hasMore": true,
      • "perPage": 100,
      • "to": "03dcf453-b9d3-4cc7-be24-b0e0f0453fb2"
      }
    },
  • "jsonapi": {
    • "version": "1.0"
    },
  • "links": {},
  • "data": [
    • {
      • "id": "a830fb5a-c2f9-4227-a46a-4e1c72b5f4c1",
      • "type": "catalog-integration-result",
      • "attributes": {
        }
      },
    • {
      • "id": "a52bdb84-8d4c-49f6-9457-6aafda51abda",
      • "type": "catalog-integration-result",
      • "attributes": {
        }
      },
    • {
      • "id": "1cd7c89c-9428-44c5-9a77-9448467453c3",
      • "type": "catalog-integration-result",
      • "attributes": {
        }
      },
    • {
      • "id": "2246214c-f7b8-4d84-8fd4-de957c192b9a",
      • "type": "catalog-integration-result",
      • "attributes": {
        }
      },
    • {
      • "id": "a830fb5a-c2f9-4227-a46a-4e1c72b5f4c2",
      • "type": "catalog-integration-result",
      • "attributes": {
        }
      }
    ]
}

Integration

Update status of External Integration

Allows to notify Ankorstore about changing the status of an integration of external platform

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

application/vnd.api+json

+
Request Body schema: application/json
required
platform
required
string
Allowed values: "shopify" "woocommerce" "prestashop" "odoo" "sellsy"
status
required
string
Allowed values: "enabled" "disabled"

Responses

Request samples

Content type
application/json
{
  • "platform": "shopify",
  • "status": "enabled"
}

Response samples

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

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

+

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

+

Please, consider updating your API clients in favor of using orderItems.productVariant instead of orderItems.productOption +to avoid any issues in the future. For the time being, the API still supports both approaches, but we strongly encourage +you to not rely on the deprecated resources anymore because we cannot fully guarantee their stability due to some technical limitations.

+
+ +

Important Fields within Internal Order resource

+

If the field contains no data, it will be null. The only exception currently to this is shippingOverview which can +be viewed below. The fields listed below are not all the fields, please see the API specification for all of them.

+

Status status

+

The status field is the current state of the order, below is a table that describes each step:

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

+

Requesting fulfillment by Ankorstore Logistics for an Internal Order

+

Can be performed when the order is in brand_confirmed.

+

Ankorstore Logistics will fulfill the order and ship it to the retailer. +The order will move from brand_confirmed to fulfillment_requested.

+

Must be preceded by a fulfillability check, since it requires +the brand to be enrolled with Ankorstore logistics, and sufficient stock to be available in an Ankorstore warehouse.

+

Validation errors can include:

+
    +
  • not_a_fulfillment_brand - The brand is not enrolled with Ankorstore Logistics
    • +
  • unavailable_items - One or more items are not available in the warehouse. The response will include a list of the +unavailable items, which map to productVariant.fulfillableId
    • +
  • already_being_fulfilled - The order is already being fulfilled
    • +
  • not_available_for_international_orders - Fulfillment is currently not available for orders crossing a customs border
    • +
  • stock_is_being_transferred - The stock is currently being transferred between warehouses
    • +
+

Available operations on Internal Orders

+ +

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&=fulfillableIds[]=e5e91243-d11a-47a3-9308-22af70da5bc4
+
+

and get quantity information for the given fulfillables from the response.

+

For each requested fulfillable item, the response of this endpoint contains 2 properties:

+
    +
  • unitQuantity - the total available quantity of the product, in minimal atomic units (e.g. bottles)
    • +
  • batchQuantity - the total available quantity of the batches (packs) of the product (e.g. boxes of bottles)
    • +
+

Having these 2 properties, you should check 2 things, before move on:

+
    +
  1. The planned quantity for the corresponding product in the order should not exceed unitQuantity from the response. +If the requested quantity is greater than the unitQuantity, the request will be rejected.
    2. +
  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
Allowed values: "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
{
  • "jsonapi": {
    • "version": "string",
    • "meta": { }
    },
  • "meta": {
    • "page": {
      • "from": "string",
      • "to": "string",
      • "hasMore": true,
      • "perPage": 0
      }
    },
  • "links": {
    • "first": "string",
    • "next": "string",
    • "prev": "string"
    },
  • "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
Allowed values: "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
{
  • "jsonapi": {
    • "version": "string",
    • "meta": { }
    },
  • "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 Master Order Fulfillments Relationships

Retrieve a list of fulfillment relationships for a Master Order

+
Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
orderId
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": "string",
      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "attributes": {
        },
      • "links": {
        },
      • "relationships": {
        }
      }
    ],
  • "jsonapi": {
    • "version": "string",
    • "meta": { }
    },
  • "included": [
    • {
      • "type": "string",
      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "attributes": {
        }
      }
    ]
}

List Master Order Fulfillments

Retrieve a list of fulfillments for a Master Order

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

application/vnd.api+json

+

Responses

Response samples

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

List master order shipment tracking

Retrieve shipment information like the parcels and the tracking information

+
Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
orderId
required
query Parameters
include
string
Allowed value: "shipmentParcel"
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

+

Responses

Response samples

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

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
Allowed values: "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": {
      • "masterOrderId": "52d7c518-b820-41af-9cc4-59dae40f2c73",
      • "status": "invoiced",
      • "reference": 3434273911,
      • "brandCurrency": "EUR",
      • "brandNetAmount": 20596,
      • "brandTotalAmount": 23405,
      • "brandTotalAmountVat": 0,
      • "brandTotalAmountWithVat": 23405,
      • "brandRejectReason": null,
      • "retailerRejectReason": null,
      • "retailerCancellationRequestReason": null,
      • "billingName": "Charles Attan",
      • "billingOrganisationName": "Jumbo",
      • "billingStreet": "Kortricklaan 101",
      • "billingPostalCode": "8121 GW",
      • "billingCity": "Arnhem",
      • "billingCountryCode": "NL",
      • "submittedAt": "2022-03-15T10:05:09+00:00",
      • "shippedAt": "2022-03-17T15:05:19+00:00",
      • "brandPaidAt": null,
      • "createdAt": "2022-03-13T16:36:24+00:00",
      • "updatedAt": "2022-03-31T11:57:13+00:00",
      • "shippingMethod": "ankorstore",
      • "shippingOverview": {
        }
      }
    },
  • "included": [
    • {
      • "type": "retailer",
      • "id": "3b656e82-0260-1ecb-9e4c-0242ac170007",
      • "attributes": {
        }
      }
    ]
}

Check Internal Order Fulfillability

Check whether an internal order can be fulfilled by Ankorstore logistics

+
Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
order
required
header Parameters
Accept
string

application/vnd.api+json

+

Responses

Response samples

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

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
object
One of
type
required
string
Allowed 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
Allowed 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 NAFO External Order

Creates a new External Order of type nafo

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

+
recipientType
string
Default: "business"
Allowed values: "business" "consumer"

The type of recipient for this order

+

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",
  • "recipientType": "business"
}

Response samples

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

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: 
 orders/:orderId/shipping-quotes]
+    B.1 --> B.2{Is the shipping list empty ?}
+    B.2 -- NO --> B.YES[I'm happy with at least one proposed quote]
+    B.2 -- YES --> B.NO[I can consider to ship with my custom solution]
+    B.YES --> D[I Confirm the quote: 
 shipping-quotes/:quoteId/confirm]
+    B.NO --> A
+    A[Start] --> C[I want to ship with custom: 
 orders/:orderId/ship/custom]
+    C --> C.1[Get the quote]
+    C.1 --> D
+
+ +

Shipping Methods

+

Within the shippingOverview object, there is a field that holds the supported shipping methods for an order:

+
{
+  "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 : 
 orders/:orderId/ship/custom
+  participant SC as Confirm : 
 shipping-quotes/:quoteId/confirm
+  participant SH as Shipped
+
+  O->>SWC: Generate quote
+  SWC-->>O: Quote OK
+  O->>SC: Confirm quote
+  SC->>SH: Status
+  SC-->>O: OK
+
+ +
+ +

In the ship/custom endpoint response, the quote uuid generated is returned in the latestQuote part:

+
 {
+   "latestQuote": {
+     "id": "1edd395f-5b57-62ac-9698-521a54b4405f",
+     "provider": "custom",
+     ...
+   }
+ }
+
+
+ +

Shipping with Ankorstore (asynchronous)

+

When calling the confirm action for the order's Ankorstore shipping quote, the returned order resource's status +will still be brand_confirmed. A job in the background will generate the shipping labels for the order. +It is this background processing that moves the status to shipping_labels_generated.

+
+ +

How will I know when the labels have been generated?

+

Right now, the order must be polled periodically. Checking every minute would be suitable to detect the status change +and then pull the label PDF data within the shippingOverview of an order resource.

+
+ +
+sequenceDiagram
+  participant O as Order
+  participant SWA as Ship with Ankor : 
 orders/:orderId/shipping-quotes
+  participant SC as Confirm shipping : 
 shipping-quotes/:quoteId/confirm
+  participant BG as Async Processing
+  participant C as Carrier
+  participant SH as Shipped
+
+  O->>SWA: Get shipping quote list
+  SWA-->>O: I accept one quote
+  O->>SC: I confirm the quote
+  SC-->>O: OK status=brand_confirmed
+  SC-->>BG: Dispatch generate labels job
+  Note over SC,BG: Async worker job
+  BG-->>O: Labels generated, status=shipping_labels_generated
+  Note over BG,O: (Async worker)
+  C-->>SH: Parcels scanned, status=shipped
+  Note over C,SH: (External service)
+
+ +

At step 6 (shipping labels generated) the download URL's for each packages label will be available within +the shippingOverview of an order resource. These labels are in PDF format and will also be visible in order details page on Ankorstore.

+

Schedule a Pickup

+

If the brand is not taking the parcels to the local drop-off point for the carrier the brand can schedule a pickup +for this order. A pickup can only be scheduled on a working day (monday to friday). +For full information please refer to the API documentation.

+
+ +

Pickup is not accepted

+

For now, Ankorstore does not know in advance which date/time configuration is available, +if the requested pickup is denied please try a different date or time frame.

+

⚠️ Deprecation notice

+ +

Some of the endpoints and documents from this section are deprecated and will be removed in the future. +You can temporarily still find them here.

+

List master order shipment tracking

Retrieve shipment information like the parcels and the tracking information

+
Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
orderId
required
query Parameters
include
string
Allowed value: "shipmentParcel"
header Parameters
Accept
string
Default: application/vnd.api+json

application/vnd.api+json

+

Responses

Response samples

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

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

+

Responses

Request samples

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

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

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"
Allowed values: "full_page" "default"

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

+
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": {
      • "masterOrderId": "a35ec01f-d2b7-4124-a7ed-c82320c629fa",
      • "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 non-empty unique
Array (non-empty)
length
required
integer <= 274
width
required
integer <= 274
height
required
integer <= 274
distanceUnit
required
string
Allowed value: "cm"

The unit of distance

+
weight
required
integer [ 1 .. 30000 ]
massUnit
required
string
Allowed 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

+
query Parameters
include
string
Allowed value: "statusUpdates"

A comma-separated list of resources to include (e.g: statusUpdates)

+
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": [
        ],
      • "shippedItems": [
        ],
      • "recipientType": "consumer"
      },
    • "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": { }
      }
    ]
}

List lots in the warehouse

Returns a list of lots

+
Authorizations:
ProductionOAuth2ClientCredentials
query Parameters
page[limit]
integer
page[offset]
integer
sort
string
Allowed values: "availableQuantity" "expiryDate" "lotNumber" "sellByDate" "fulfillmentItems.productName" "-availableQuantity" "-expiryDate" "-lotNumber" "-sellByDate" "-fulfillmentItems.productName"

Specify what attribute(s) to sort by

+
filter[minAvailableQuantity]
integer

Request instances with a available quantity greater or equal to a given value

+
filter[minSellByDate]
string <datetime>

Request instances with a last sell by date greater or equal to a given value

+
filter[maxSellByDate]
string <datetime>

Request instances with a last sell by date smaller or equal to a given value

+
include
any

A comma-separated list of resources to include (e.g: fulfillmentItem)

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

Webhooks

ℹ️ This section describes the API endpoints which can be used for managing webhook subscriptions.

+

💡 Overview

In order to be able to manage Webhook Subscriptions via API you should understand the relationship model +around webhook notifications system. In general, a Webhook Subscription always contains a list of chosen events +and always belongs to an application. More on this later.

+

Application

+

Application is a representation of a single private integration. Whenever you create a new set of credentials for +accessing API in your account, under the hood you create an Application entity. Once created, the entity allows you +to attach as many Webhook Subscriptions as needed. It means, there's no way to manage Webhook Subscriptions outside of +Application context and this restriction is also reflected in the current API architecture.

+

Webhook Subscription

+

Webhook Subscription is an entity representing "an intent of receiving HTTP requests to the specified URL whenever +one of the chosen Webhook Subscription Events is triggered on the platform". For every new URL you should create a +separate Webhook Subscription.

+

Webhook Subscription Events

+

Webhook Subscription Event is a name of the corresponding event fired on certain conditions on the platform. There are +a list of only valid and supported events which can be used in the Webhook Subscription management. You can fetch this +list using a corresponding endpoint

+

💡 How to create a new webhook subscription?

1. Find ApplicationID

+

As it was mentioned above, Webhook Subscription always belong to some application. Hence, you should start from +finding out the ID of the target Application in order to link the new Webhook Subscription to it. For this purpose +you should use List Applications endpoint. This endpoint returns +a list of all available Applications in your account, so you could identify the needed one by name, developerEmail +or clientId in the Application resource body:

+

GET https://ankorstore.com/api/v1/applications

+
{
+  "data": {
+    "id": "43efbfbd-bfbd-1eef-1e6a-6200efbfbdef",
+    "type": "application",
+    "attributes": {
+      "name": "My Application",
+      "developerEmail": "dev@acme.com",
+      "clientId": "k322k7frs87e8w7hri3jkke7ry7",
+      "clientSecret": null
+    }
+  }
+}
+
+

NOTE: The client secret in the response is always null due to security reasons. The actual client secret +can be seen only via UI and only once - during the creation of the application.

+

2. Find valid webhook events to subscribe to

+

Next step should be to find the valid names of the webhook events which you could use in the create webhook request +payload:

+

GET https://ankorstore.com/api/v1/webhook-subscriptions/events

+
{
+  "data": [
+    {
+      "type": "webhook-subscriptions/events",
+      "id": "order.brand_created"
+    },
+    {
+      "type": "webhook-subscriptions/events",
+      "id": "order.brand_accepted"
+    }
+  ]
+}
+
+

You can find detailed description of each event in the dedicated section of the docs.

+

3. Create webhook subscription

+

Now you are all set for creating actual webhook subscription. The prerequisites for this step are:

+
    +
  • The Application ID from step 1 (43efbfbd-bfbd-1eef-1e6a-6200efbfbdef in this example)
    • +
  • The chosen events from step 2 (e.g. order.brand_created and order.brand_accepted) +With this setup the final request should look like:
    • +
+

POST https://ankorstore.com/api/v1/webhook-subscriptions

+
{
+  "data": {
+    "type": "webhook-subscriptions",
+    "attributes": {
+      "url": "https://my-app.com/webhook-listener",
+      "events": [
+        "order.brand_created",
+        "order.brand_accepted"
+      ]
+    },
+    "relationships": {
+      "application": {
+        "data": {
+          "type": "applications",
+          "id": "43efbfbd-bfbd-1eef-1e6a-6200efbfbdef"
+        }
+      }
+    }
+  }
+}
+
+

After this request is succeeded, you will start receiving notification about chosen events on the chosen URL.

+

💡 How to manage existing Webhook Subscriptions?

For most of the operations with an existing Webhook Subscription you need to fetch its ID first. It can be achieved by +using List Applications endpoint and explicit including +the Webhook Subscription resource into the response.

+

GET /api/v1/applications?include=webhookSubscriptions

+
{
+  "data": {
+    "id": "`43efbfbd-bfbd-1eef-1e6a-6200efbfbdef",
+    "type": "applications",
+    "attributes": {},
+    "relationships": {
+      "webhookSubscriptions": {
+        "data": [
+          {
+            "type": "webhook-subscriptions",
+            "id": "a863e15d-3d20-4af2-b92b-d9590a4a9606"
+          }
+        ]
+      }
+    }
+  },
+  "includes": [
+    {
+      "type": "webhook-subscriptions",
+      "id": "a863e15d-3d20-4af2-b92b-d9590a4a9606",
+      "attributes": {
+        "url": "https://my-app.com/webhook-listener",
+        "events": [
+          "order.brand_created",
+          "order.brand_accepted"
+        ],
+        "signingSecret": "LQxZs6kiSyNr45hjT32OsntYddzH4BvToLIQcgSL"
+      }
+    }
+  ]
+}
+
+

The data in this response gives you an idea about the current Webhook Subscription state and also lets you update +or delete Webhook Subscriptions, whenever needed. For updating or deleting Webhook Subscription you need to use the +Webhook Subscription ID received in the response (a863e15d-3d20-4af2-b92b-d9590a4a9606 in this particular case). Please +refer to the Update webhook subscription +and Delete webhook subscription endpoints +for detailed information.

+

List Applications

List existing application for the current authenticated user

+
Authorizations:
ProductionOAuth2ClientCredentials
header Parameters
Accept
string

application/vnd.api+json

+

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": {
    • "id": "43efbfbd-bfbd-1eef-1e6a-6200efbfbdef",
    • "type": "application",
    • "attributes": {
      • "name": "My sandbox",
      • "developerEmail": "dev@my-app.com",
      • "clientId": "k322k7frs87e8w7hri3jkke7ry7",
      • "clientSecret": null
      }
    },
  • "included": [
    • {
      • "type": "string",
      • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      • "attributes": {}
      }
    ],
  • "jsonapi": {
    • "version": "string",
    • "meta": { }
    }
}

List Webhook Subscription Events

Returns a list of webhook events available in the system

+
Authorizations:
ProductionOAuth2ClientCredentials

Responses

Response samples

Content type
application/vnd.api+json
{
  • "data": [
    • {
      • "type": "order.brand_created",
      • "id": "1ef27156-618d-6b1e-996c-0ef14cd127ec"
      },
    • {
      • "type": "order.brand_accepted",
      • "id": "1ef27156-618d-6b1e-996c-0ef14cd127ec"
      },
    • {
      • "type": "order.shipping_labels_generated",
      • "id": "1ef27156-618d-6b1e-996c-0ef14cd127ec"
      },
    • {
      • "type": "order.shipped",
      • "id": "1ef27156-618d-6b1e-996c-0ef14cd127ec"
      },
    • {
      • "type": "order.shipment_received",
      • "id": "1ef27156-618d-6b1e-996c-0ef14cd127ec"
      },
    • {
      • "type": "order.shipment_refused",
      • "id": "1ef27156-618d-6b1e-996c-0ef14cd127ec"
      },
    • {
      • "type": "order.brand_paid",
      • "id": "1ef27156-618d-6b1e-996c-0ef14cd127ec"
      },
    • {
      • "type": "order.cancelled",
      • "id": "1ef27156-618d-6b1e-996c-0ef14cd127ec"
      }
    ]
}

Add Webhook Subscription to Application

Adds a new webhook subscription to the existing application

+
Authorizations:
ProductionOAuth2ClientCredentials
Request Body schema: application/vnd.api+json
required
object
type
required
string
Allowed value: "webhook-subscription"
required
object
url
required
string <uri>
events
required
Array of strings non-empty unique
required
object
required
object
required
object
type
required
string
id
required
string

Responses

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "type": "webhook-subscription",
    • "attributes": {},
    • "relationships": {
      • "applications": {
        }
      }
    }
}

Response samples

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

Update Application Webhook Subscription

Update application subscription with given ID

+
Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
webhookSubscriptionId
required
string

Webhook Subscription ID

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

application/vnd.api+json

+
Request Body schema: application/vnd.api+json
required
object
type
required
string
id
required
string
object
url
required
string <uri>

URL of the service where webhook request will be sent when one of the events from the list occurs

+
events
required
Array of strings non-empty unique
Items Allowed values: "order.brand_created" "order.brand_accepted" "order.brand_rejected" "order.shipping_labels_generated" "order.shipped" "order.shipment_received" "order.shipment_refused" "order.brand_paid" "order.cancelled"

Responses

Request samples

Content type
application/vnd.api+json
{}

Response samples

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

Delete Application Webhook Subscription

Delete application webhook subscription by given ID

+
Authorizations:
ProductionOAuth2ClientCredentials
path Parameters
webhookSubscriptionId
required
string

Webhook Subscription ID

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

application/vnd.api+json

+

Responses

Response samples

Content type
application/vnd.api+json
{
  • "jsonapi": {
    • "version": "1.0"
    },
  • "errors": [
    • {
      • "detail": "Unauthorized",
      • "status": "401"
      }
    ]
}

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
Allowed values: "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 non-empty unique
Array (non-empty)
length
required
integer <= 274
width
required
integer <= 274
height
required
integer <= 274
distanceUnit
required
string
Allowed value: "cm"

The unit of distance

+
weight
required
integer [ 1 .. 30000 ]
massUnit
required
string
Allowed 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
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": {
        }
      }
    }
}
+ + + +