Ankorstore APIs (1.0.0)

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

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

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

🔗 Learn more about JSON:API filters

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

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=*"
}

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.

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

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

Subscribing

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

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

Format

The webhook payload sent is the same as the resource object provided by the API. For example, if an order.* webhook is fired the resource will be OrderResource.

The only difference is that within the top level meta object you will receive an event object with details of the webhook which will look like this:

POST https://your-webhook-url.com/webhooks/handle

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

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

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.

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

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

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

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

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

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

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

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

ℹ️ This section describes the API endpoints that you can use to manage your catalog resources, such as products, product variants etc.

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.

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

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: