Sure Imports Shipping Affiliate API: Integration Guide for Businesses

The Sure Imports shipping affiliate API allows an approved business affiliate to create shipping requests for its customers without sending staff through a separate manual form for every enquiry. It is designed for commerce tools, procurement platforms, agencies, communities and operational systems that already collect the basic customer and cargo information.

The integration preserves affiliate ownership at the request level. When Sure Imports accepts a request created with your API key, the response includes the attribution identifier and lock time. If the linked shipping invoice is eventually paid and remains eligible, commission is calculated using the final billable shipping quantity and the rate configuration for that plan.

API base resources

Read the live OpenAPI contract during implementation rather than copying an old payload from a screenshot or article. The machine-readable contract is the source for current field constraints and response shapes.

Authentication and key safety

The API uses a Bearer API key issued in the affiliate developer workspace. Shipping creation and retrieval require the appropriate shipping:write and shipping:read scopes. A secret is displayed once and can be revoked, so store it in a server-side secret manager immediately.

Never place the key in frontend JavaScript, a mobile application bundle, analytics events, support screenshots or a public source repository. If a key may have leaked, revoke it and issue a replacement. Use separate keys where independent systems need distinct audit and rotation boundaries.

Discover a plan before creating a request

A shipping plan determines operational context including destination and billing unit. Query the plan list using the customer’s destination, present only suitable choices in your interface and store the selected shippingPlanId. Do not hard-code an identifier indefinitely because available plans can evolve.

The request quantity must be expressed in the returned plan’s unit. The current contract uses shipment.estimatedQuantity. Your interface should label that value clearly as an estimate and should not imply that it fixes the final freight charge or commission.

Create an idempotent shipping request

POST /api/v1/shipping-requests
Authorization: Bearer YOUR_SECRET_API_KEY
Idempotency-Key: your-stable-request-key
Content-Type: application/json

{
  "customer": {
    "firstName": "Customer first name",
    "email": "customer@example.com",
    "phone": "+234..."
  },
  "shipment": {
    "shippingName": "Internal shipment label",
    "destinationCountry": "Nigeria",
    "shippingPlanId": "selected-plan-id",
    "estimatedQuantity": 25,
    "description": "Clear description of the goods"
  },
  "externalReference": "your-unique-reference"
}

The Idempotency-Key must contain 8 to 120 characters. Generate one stable key for the logical creation attempt and reuse it when retrying after a timeout. Do not generate a fresh key for every retry, because that defeats duplicate protection.

Use a unique external reference that maps to your own order, lead or service record. Store the request ID and status returned by Sure Imports. A successful creation returns HTTP 201 with the request identifiers, customer identifier and locked ownership details.

Attribution and commission semantics

An accepted API-created request is owned by the affiliate whose active key created it. That ownership is locked for the request. Request ownership does not overwrite the customer’s general affiliate relationship for unrelated journeys.

Request creation does not itself generate payable commission. The early estimated quantity does not set commission either. When a linked shipping invoice becomes fully paid, the system uses the final eligible billable KG or CBM and the plan’s configured commission rate and currency to create the commission snapshot.

Design for errors and retries

Production integration checklist

• Keep keys in a managed server-side secret store and document rotation ownership.
• Cache plan discovery briefly, but refresh when a plan is unavailable or changes.
• Validate required customer and shipment fields before making the API call.
• Use one stable idempotency key and one unique external reference per logical request.
• Log request IDs, response status and your reference without logging the API secret.
• Handle 429 responses using Retry-After and bounded exponential backoff.
• Reconcile request status and eligible commission through the affiliate dashboard and exports.
• Tell customers that Sure Imports will assess and confirm the request; do not present an estimate as a final quote.

Privacy and customer communication

Submit customer data only when you have a lawful basis and have told the customer that the information will be shared with Sure Imports to handle the shipping request. Collect only the fields needed for the transaction. Protect exported reports and restrict access to operational staff.

The affiliate dashboard uses privacy-conscious reporting, including masked information where appropriate. Your own application should follow the same principle. Avoid placing full customer data in idempotency keys, external references or logs.

The practical next step

Create an affiliate account, open the developer workspace, read the live OpenAPI contract and implement plan discovery before request creation. Start with a small controlled flow, verify attribution and reconciliation, then expand the integration once error handling and customer consent are proven.

Frequently asked questions

Can the API create shipping requests for my customers?

Yes. An approved business affiliate can create requests under its API credentials and preserve request-level affiliate attribution.

Which field contains the estimated weight or volume?

Use shipment.estimatedQuantity in the unit returned by the selected shipping plan.

Why is an idempotency key required?

It lets a client safely retry a creation attempt without unintentionally producing duplicate requests.

Does HTTP 201 mean commission has been earned?

No. It means the request was accepted. Eligible commission depends on a fully paid linked invoice, final billable quantity and programme review.

Where is the API documentation?

The developer workspace links to the documentation, and the current OpenAPI 3.1 contract is available from the public API endpoint listed above.

Ready to build a commission channel around real import and shipping needs? Create a free Sure Imports affiliate account, review the affiliate terms, and use the current service links and commission rules shown in your dashboard.