Orders API (B2B)

Create and retrieve orders via the API.
This endpoint is idempotent and protected using Laravel Sanctum.

---

Authentication

All requests must be authenticated using a Bearer token.

Required headers

Authorization: Bearer <SANCTUM_TOKEN> Accept: application/json Content-Type: application/json

If authentication fails, the API returns 401 Unauthorized.

---

Create Order (Idempotent)

Create a new order (each giftcard is an unique order) or retrieve an existing one using a unique api_id.

POST /api/orders

Idempotency

• If an order with the same api_id already exists for the same API user,
  the API will not create a new order and returns the existing order.
• If the api_id exists but belongs to a different API user, the request fails with 422.
• It is recommended to use a unique prefix per API user to avoid conflicts.

---

Request Body

Master fields

Field	Type	Required	Description
api_id	string	Yes	Unique reference from the B2B client
product_id	string	Yes	EAN of the product
amount	integer	Yes	Value of the giftcard

Example Request

{
  "api_id": "B2B-GC-10001",
  "product_id": 2002,
  "email": "inkoop@bedrijf.nl",
  "amount": 50
}

Responses

201 Created (New Order)

{
  "giftcard": {
    "id": 12345,
    "store_id": 1,
    "product_id": 2002,
    "email": "inkoop@bedrijf.nl",
    "value": 50,
    "type": "digital",
    "status": "pending",
    "code": null,
    "pin": null,
    "created_at": "2026-02-03T12:00:00Z",
    "updated_at": "2026-02-03T12:00:00Z"
  }
}

200 OK (Order Already Exists)

When the same api_id is used by the same API user, we will return the same response as above with status code 200 OK.

Giftcard status fields

When an order contains giftcard products, the API returns giftcard-related status fields on both order level and item level.

Response fields (Giftcards)

Field	Type	Description
status	string	Giftcard generation status. Possible values: success, pending, error

• success → the giftcard has been generated
• pending → the giftcard is still pending
• error → the giftcard could not be retrieved

---

Item-level (giftcard products)

Each item in the items array contains giftcard-related fields.

Field	Type	Description
status	string	Status of the individual giftcard
code	string | null	Generated giftcard code (if available)
pin	string | null	Giftcard PIN (if applicable)

Possible giftcard_status values

Value	Meaning
success	Giftcard successfully generated
pending	Giftcard generation still in progress
error	An error occurred while generating the giftcard

Error Responses

422 Validation Error

    {
    "message": "The given data was invalid.",
        "errors": {
        "product_id": [
          "Ongeldige product ID."
        ]
    }
}

401 Unauthorized

Returned when:

No token is provided

Token is invalid or expired

500 Server Error

{
"message": "Server error"
}

Orders are created directly in status:

• Duplicate requests are safe due to idempotency