FBN Inbound API Overview

The FBN Inbound API allows partners to create and manage ASN shipments for forward deployment into FBN warehouses. Partner identity is resolved from the authentication context — all operations are scoped to the authenticated partner.

Base URL

All API requests are sent to:

https://noon-api-gateway.noon.partners/inbound

All endpoints are prefixed with /v1. For example:

POST https://noon-api-gateway.noon.partners/inbound/v1/shipment/create

Authentication

The FBN Inbound API uses the same authentication mechanism as all other Noon Partner APIs. Partner identity is resolved automatically from your authentication headers — all operations are scoped to your account.

See Authenticating Your Requests for instructions on obtaining and using credentials.

Rate Limits

Limit type	Value
Max requests per minute	1,500
Burst limit	1,500 requests per minute

Requests exceeding the rate limit return HTTP 429 Too Many Requests. Implement exponential backoff when retrying.

Conventions

Timestamps

All timestamps use ISO 8601 format in UTC:

2026-03-09T14:30:00Z

Dates

Scheduled dates and other date-only fields use YYYY-MM-DD format:

2026-03-09

Country Codes

Country codes follow the two-letter ISO 3166-1 alpha-2 standard (e.g., AE, SA, EG).

Pagination

Paginated endpoints return a next_token field in the response. Pass this token in the next request to fetch the following page. When next_token is null or absent, you have reached the last page.

GET /v1/shipment/list?next_token=<token_from_previous_response>&page_size=50

Idempotency

CreateShipment is idempotent: retrying with the same exref_nr and shipment_type returns the existing ASN rather than creating a duplicate.

Inbound Lifecycle Flow

CREATE (Header) → ADD ITEMS → SEAL → CHECK AVAILABILITY → SCHEDULE → RECEIVING → INBOUNDED

See Appendix A for full status descriptions and all possible transitions.

Workflow Overview

Step 1 — Create a shipment

Create an ASN header using CreateShipment. The ASN starts in CREATED status with no items.

Step 2 — Check eligible items

Use the ListEligibleItems endpoint to see which of your catalog items are eligible for FBN inbound. Only items with a mapped barcode, title, and uploaded image are eligible.

Step 3 — Add items

Add items to the draft ASN using UpdateShipmentItems. You can call this multiple times to add or update quantities (upsert). Maximum 1,000 items per call.

Step 4 — Seal the shipment

Finalize the ASN using UpdateShipmentStatus with STATUS_ACTION_SEAL. After sealing, items cannot be modified. Status transitions from CREATED → SEALED.

Step 5 — Check slot availability

Retrieve eligible warehouses and their available check-in dates and time slots using GetSlotAvailability.

Step 6 — Schedule the shipment

Book a warehouse slot using ScheduleShipment with the warehouse code, date, and time slot from the previous step. Status transitions from SEALED → SCHEDULED.

Step 7 — Deliver inventory

Physically deliver the shipment to the warehouse at the scheduled time. Noon will update the ASN to INBOUNDED after processing.

For full endpoint details, see the FBN Inbound API Reference.

Key Constraints

warning

Bulky and non-bulky items cannot be mixed in the same ASN. Each ASN must contain items of the same storage type.
One FBN warehouse per country is designated for inbound. Use GetSlotAvailability to find the correct warehouse for each country.
Maximum 1,000 items per API call for item add/delete operations.
The FBN_GLOBAL shipment type is used for ERP integrations.

Error Handling

All APIs return a standardized error response:

{
  "detail": {
    "code": "MACHINE_READABLE_CODE",
    "message": "Human-readable description of what went wrong"
  }
}

See Appendix B for the full list of error codes per endpoint, and Appendix C for example error payloads.

Appendix A: ASN Status Flow

         /--> CANCELED          /--> CANCELED
        /                      /
CREATED --> SEALED --> SCHEDULED --> RECEIVING --> INBOUNDED
                 \
                  \--> EXPIRED

Status	Description
`ASN_STATUS_CREATED`	Draft ASN. Items can be added, updated, or deleted.
`ASN_STATUS_SEALED`	Finalized. Items locked. Ready for scheduling.
`ASN_STATUS_SCHEDULED`	Slot reserved. Awaiting physical delivery.
`ASN_STATUS_RECEIVING`	Goods are being received at the warehouse.
`ASN_STATUS_INBOUNDED`	Goods fully received and put away.
`ASN_STATUS_CANCELED`	Canceled by the partner. Terminal state.
`ASN_STATUS_EXPIRED`	Not sealed or scheduled within the required window. Terminal state.

Appendix B: Error Code Reference

Code	HTTP Status	APIs	Description
`UNAUTHORIZED`	401	All	Missing or invalid authentication token.
`FORBIDDEN`	403	All	Partner does not own this ASN or country mismatch.
`WRONG_COUNTRY`	403	Create, Status (seal)	Country code in request does not match the authenticated country.
`ASN_NOT_FOUND`	404	All	ASN reference does not exist.
`VALIDATION_ERROR`	422	All	Malformed payload — missing required fields, wrong types.
`ITEM_VALIDATION_FAILED`	400	Update Items, Delete Items	One or more items failed catalog validation (see details array).
`ITEMS_LIMIT_EXCEEDED`	400	Update Items, Delete Items	Request exceeds the maximum of 1,000 items per call.
`PARTNER_SKU_NOT_FOUND`	—	Update Items, Delete Items	(Item detail) `partner_sku` could not be resolved for this partner.
`INACTIVE_PSKU_CODE`	—	Update Items	(Item detail) `partner_sku` resolves to an inactive product.
`NO_MAPPED_PBARCODE`	—	Update Items	(Item detail) `partner_sku` has no active barcode mapping.
`INVALID_STORAGE_TYPE`	—	Update Items	(Item detail) Invalid `storage_type`.
`INVALID_ASN_STATUS`	409	Status, Update Items, Delete Items, Schedule, Availability	ASN is not in the required status for this operation.
`CAPACITY_EXCEEDED`	400	Schedule	No available capacity for the requested date/slot.
`CANNOT_CANCEL`	409	Status (cancel)	ASN is manifested or inbound has started.
`CANNOT_RESCHEDULE`	409	Status (reschedule)	Scheduled slot has already started.
`RATE_LIMIT_EXCEEDED`	429	All	Too many requests. Retry with exponential backoff.
`INTERNAL_ERROR`	500	All	Unexpected server error. Retry with backoff.

Appendix C: Common Errors Across All APIs

401 Unauthorized

{
  "detail": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid authentication token"
  }
}

422 Unprocessable Entity

{
  "detail": {
    "code": "VALIDATION_ERROR",
    "message": "field required",
    "details": [
      {"field": "asn_nr", "message": "field required"}
    ]
  }
}

500 Internal Server Error

{
  "detail": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred. Please try again later."
  }
}

Base URL​

Authentication​

Rate Limits​

Conventions​

Timestamps​

Dates​

Country Codes​

Pagination​

Idempotency​

Inbound Lifecycle Flow​

Workflow Overview​

Step 1 — Create a shipment​

Step 2 — Check eligible items​

Step 3 — Add items​

Step 4 — Seal the shipment​

Step 5 — Check slot availability​

Step 6 — Schedule the shipment​

Step 7 — Deliver inventory​

Key Constraints​

Error Handling​

Appendix A: ASN Status Flow​

Appendix B: Error Code Reference​

Appendix C: Common Errors Across All APIs​