Code Reservation

Code reservation collection manages the batch reservation of unique identifier codes for specific entities, purposes, or export operations, providing tracking and export capabilities for reserved code sets.

The code_reservation Object

Code reservation collection handles the allocation and management of batches of unique codes for specific use cases, supporting various export formats and maintaining reservation status and quantities.

Field Name	Type	Description
id	uuid	Primary key. Unique identifier for the code reservation (UUID format).
user_created	object	User who created the code reservation. Read-only. Links to directus_users.
date_created	datetime	Timestamp in ISO 8601 when the code reservation was created. Read-only.
user_updated	object	User who last updated the code reservation. Read-only. Links to directus_users.
date_updated	datetime	Timestamp in ISO 8601 when the code reservation was last updated. Read-only.
reserved_for	object	Organisation this set of codes is reserved for. Links to organisation.
code_type	string	Type of codes being reserved (e.g., "sgtin", "sscc", "grai", "short_code").
quantity	integer	Number of codes requested for reservation.
status	string	Current status of the reservation. Default: "new". Values: "new", "in_progress", "complete", "error".
export_type	string	Format for code export. Default: "csv". Values: "csv", "json", "xml", etc.
export_file	object	Generated export file containing the reserved codes. Links to directus_files.
url_suffix	string	Optional URL suffix to append to generated digital links.
product	string	Product identifier the reserved codes are associated with (primary key from product collection).
quantity_reserved	integer	Number of codes successfully reserved.
error_message	string	Error message if the reservation failed during processing.
reference_id	string	Optional reference identifier for tracking purposes (e.g., purchase order, batch name).
purchase_order	object	Purchase order associated with this reservation.
codes	array of objects	Unique codes included in this reservation.

---

Sub-Objects

User Object (user_created, user_updated)

See Users for the full schema.

Organisation Object (reserved_for)

See Organisation for the full schema.

File Object (export_file)

See Files for the full schema.

---

List Code Reservations

List existing code reservations.

REST

GET /items/code_reservation

GraphQL

query {
  code_reservation {
    id
    reserved_for
    code_type
    quantity
    status
    export_type
    product
    quantity_reserved
    reference_id
    date_created
    date_updated
  }
}

Query Parameters

Supports all global query parameters.

Returns

An array of up to limit code reservation objects. If no items are available, data will be an empty array.

---

Retrieve a Code Reservation

Retrieve a specific code reservation by ID.

REST

GET /items/code_reservation/:id

GraphQL

query {
  code_reservation_by_id(id: "code_reservation_id") {
    id
    reserved_for
    code_type
    quantity
    status
    export_type
    export_file {
      id
      filename_download
    }
    url_suffix
    product
    quantity_reserved
    error_message
    reference_id
    user_created {
      id
      first_name
      last_name
    }
    date_created
    user_updated {
      id
      first_name
      last_name
    }
    date_updated
  }
}

Returns

Returns a code reservation object if a valid primary key was provided.

---

Create a Code Reservation

Create a new code reservation.

REST

POST /items/code_reservation

{
  "reserved_for": "/417/9312345000012",
  "code_type": "sgtin",
  "quantity": 100,
  "export_type": "csv",
  "product": "/01/19361758000003",
  "reference_id": "BATCH-2024-001"
}

GraphQL

mutation {
  create_code_reservation_item(data: {
    reserved_for: "/417/9312345000012"
    code_type: "sgtin"
    quantity: 100
    export_type: "csv"
    product: "/01/19361758000003"
    reference_id: "BATCH-2024-001"
  }) {
    id
    reserved_for
    code_type
    quantity
    status
    product
    reference_id
  }
}

Query Parameters

Supports all global query parameters.

Request Body

A partial code reservation object.

Returns

Returns the code reservation object for the created code reservation.

---

Update a Code Reservation

Update an existing code reservation.

REST

PATCH /items/code_reservation/:id

{
  "status": "complete",
  "quantity_reserved": 100,
  "reference_id": "BATCH-2024-001-UPDATED"
}

GraphQL

mutation {
  update_code_reservation_item(id: "code_reservation_id", data: {
    status: "complete"
    quantity_reserved: 100
    reference_id: "BATCH-2024-001-UPDATED"
  }) {
    id
    status
    quantity_reserved
    reference_id
  }
}

Query Parameters

Supports all global query parameters.

Request Body

A partial code reservation object.

Returns

Returns the code reservation object for the updated code reservation.

---

Delete a Code Reservation

Delete an existing code reservation.

REST

DELETE /items/code_reservation/:id

GraphQL

mutation {
  delete_code_reservation_item(id: "code_reservation_id") {
    id
  }
}

Returns

Empty body.

---

Sample Data

ID	Reserved For	Code Type	Quantity	Status	Product	Reference ID
03343178-982f-4b83-8dcb-916595070e51	/417/9312345000012	sgtin	50	complete	/01/19361758000003	RG-Cot-Cases
35ca5b51-8c2d-42bc-a39a-e8a897dff697	/417/9312345000012	sgtin	100	complete	/01/09361758000003	RG-Cot-Items
6b2f83d7-f200-4d82-a59c-969d05aacd27	/417/5555999200016	sgtin	4	complete	/01/77777666100048	abc-123
aea5a05e-2e12-4c41-b888-b96d34904cab	/417/5555999200016	sgtin	5	complete	/01/77777666100062	PO-567