Ankorstore Public API (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:

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

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

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

Retries

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

ℹ️ 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 operation can be performed at a time

Operation Statuses

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

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")
started("Processing\nStarted")
succeeded(Succeeded):::success
skipped("Processing Skipped"):::success
failed(Failed):::failure
partial(Partially Failed):::warning
report("Report\nGenerated")
notified(Callback Sent)

subgraph creating[Creating Operation]
created -- Add Products --> created
end

created -- Start processing --> 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 -- Generate report --> reporting
partial -- Generate report --> reporting
failed -- Generate report --> reporting

subgraph reporting[Reporting]
report -- Notify --> notified
end

skipped -- Generate empty report --> reporting

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

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

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

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:

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.

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.