3PL Partner API Documentation

Getting Started

This section provides an overview of the onboarding process for partners to start using the API. Typical steps include:

• Initial meetings to establish stock items available for ordering.
• Onboarding stock items with the retailer.
• Introduction to the API and its functionality.

Partners will also gain access to a self-service portal to manage users, webhook subscriptions, and API configurations.

Onboarding

Partners will follow these steps to onboard:

1. Establish stock items available for ordering.
2. Configure webhook subscriptions, including target endpoints, authentication requirements, and custom HTTP headers or parameterized URLs.
3. Access schema documents or the OpenAPI specification for integration.
4. Follow the process for managing future schema changes to ensure compatibility.

Onboarding Flow

API Overview

Environments

• Production Environment: For live operations.
• Sandbox/Emulator Environment: For testing purposes. Behaves like production but allows metadata in requests to simulate specific test scenarios (e.g., testing an order expected to fail).

Authentication

• OAuth 2.0 (Client Credentials Flow): Used for authenticating API requests.
• API Key: Only if OAuth2 can't be used for some reason.
• Webhook Authentication: Partners can define their webhook endpoint authentication requirements, supporting both OAuth 2.0 and API Keys for flexibility.

Rate Limits

Where rate limits are implemented, partners should handle 429 Too Many Requests responses by implementing retries based on the Retry-After response header.

Error Handling

1. Schema Validation Errors:
   • If a request fails JSON schema validation, a 400 Bad Request response is returned.
2. Logical Errors:
   • If the payload passes schema validation but contains logically incorrect information (e.g., unknown SKU or order ID), a webhook event will be triggered to describe the issue.

Testing Guidelines

The sandbox/emulator environment allows partners to test API functionality as they would in production. Metadata can be included in requests to simulate specific test scenarios, such as:

• Orders expected to fail.
• Simulating webhook events.

Schema Version Change Management

If the schema for a webhook event or API needs to change, the process for managing this change needs to be clearly documented in the Portal. The guidance should include information on what is considered a breaking change versus a backward-compatible change, as well as describe timelines for retiring previous versions. The Portal will likely list multiple versions of an event when configuring a subscription to a webhook, and tenants may wish to subscribe to both the current version and the new version, on different URLs, for the period of onboarding the new version. Breaking changes to a schema MUST always require a new major version of that api or event and new event versions would be considered a new webhook, requiring new subscriptions. Backwards compatible changes (new, optional fields) may not require a version increment.

Any changes, whether they are backwards compatible or not, should be raised as notifications to the owners of API Clients and Subscriptions.

Orders Flow Diagram(s)

Create Order Flow

Register an order for NEXT to fulfil.
This workflow reserves the stock for an order, before waiting for approval to fulfil, for example when a merchant is waiting for payment confirmation or fraud checks to complete.

• Orders can be pre-approved, which skips waiting for an explicit approval. Once an order is approved, the order can no longer be cancelled.
• Registering an order will reserve the stock for a period of time (TBD), after which the order will expire, and the stock will be released.

Update Order Flow

Approve or Cancel an existing order.
Approving an order releases the order for fulfilment.
Cancelling the order cancels all lines.

• Orders can be pre-approved, which skips the need to call the Update Order Status Endpoint.
• Order fulfilment is optimistic, and will try to fulfil as many order lines as possible, while cancelling any lines that cannot be fulfilled.
• Any 'in stock' items which fail fulfilment (e.g. damaged during pick/pack), will be cancelled and not automatically reordered.

Future Considerations

• A schema repository or OpenAPI specification will be maintained.
• A process for managing breaking changes to schemas will be established to ensure smooth partner integration.
• A Self-serve portal for managing technical integration.

Glossary