---
title: "Orders"
description: "Learn how to retrieve order information and manage delivery records through our Orders API."
source: "https://docs.tokenz.one/en/v2/order"
api_version: "v2"
locale: "en"
version_status: "current"
docs_stage: "prod"
---

# Orders

Learn how to retrieve order information and manage delivery records through our Orders API.

Order API provides three independent endpoints for order management. The Order Retrieval API allows you to access comprehensive order information including status, items, and customer details. The Order Cancellation API lets you void orders that are no longer needed, and the Delivery Registration API enables you to register delivery records with flexible payload structure for order fulfillment tracking.

Orders are automatically created when merchants create checkout sessions and contain all purchase details including items, amounts, and customer information.

**Amount format:** All monetary values (such as `amount` fields) are expressed in the smallest minor unit of each currency. See [Supported currencies](https://docs.tokenz.one/en/v2/checkout/currency) for the exact encoding per currency.

## Overview

The Order system provides three main API endpoints:

- **Order Retrieval API**: Access detailed order information including status, items, and customer details
- **Order Cancellation API**: Cancel an order and receive the updated order state with `canceledAt` timestamp
- **Delivery Registration API**: Register delivery records with flexibility. It accepts any JSON structure while providing warnings and suggestions for critical fields.

These APIs operate independently - you can retrieve order information at any time, and register delivery records when items are shipped or delivered. The Delivery Registration API is designed to be flexible, accepting any valid JSON payload while guiding you toward including important information through a warning system.

## Order lifecycle

Orders automatically progress through different states as payments are processed:

1. **Order Creation**: Orders are automatically created when merchants create checkout sessions
2. **Order Processing**: Orders move through various states: `requiresPayment` → `processing` → `succeeded`
3. **Order Retrieval**: Use our Orders API to access order details for fulfillment and tracking
4. **Delivery Registration**: Independently register delivery information when orders are fulfilled

### Order status values

Orders progress through the following status values:

- `requiresPayment`: Payment is still pending for this order
- `processing`: Payment has been received and the order is being processed
- `succeeded`: Order has been successfully completed
- `failed`: The order failed after processing
- `blocked`: The order is temporarily blocked from further actions
- `canceled`: The order has been canceled and will not continue processing
- `expired`: The order has expired and is no longer valid

```mermaid
sequenceDiagram;
autonumber;
participant M as Merchant App;
participant T as Tokenz API;
participant DB as Order Database;
%% Order Retrieval Flow;
Note over M,DB: Order Retrieval API;
M->>T: GET /v2/order/{id};
T->>DB: Query order details;
DB-->>T: Return order data;
T-->>M: Order details;
%% Delivery Registration Flow (Independent);
Note over M,DB: Delivery Registration API;
M->>T: POST /v2/order/{orderId}/delivery;
T->>DB: Store delivery record;
T-->>M: Delivery record confirmation;
```

## API call examples

### Order retrieval API

Get detailed information about a specific order using its ID. You can find the order ID from the Checkout Session creation response or webhook.

```bash
curl --request GET \
--url https://api.tokenz.one/v2/order/{YOUR_ORDER_ID} \
--header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
--header 'Content-Type: application/json'
```

**Response:**

```json
{
  "id": "order_1D5xA9BnKfv_t",
  "object": "order",
  "status": "requiresPayment",
  "amount": {
    "amount": 3700,
    "currency": "JPY"
  },
  "items": [
    {
      "id": "item_1D6F8mR5TnK_t",
      "detail": {
        "product": {
          "price": {
            "amount": 1200,
            "currency": "JPY"
          },
          "quantity": 3,
          "label": "ひとにぎりのエメラルド",
          "description": "80+8",
          "images": [
            "https://images.ctfassets.net/z82qbo7cv7ia/1dWPbk5Qx2M1Qikj6Knyuc/e37b2c26829c0d30793a348ae3adb3b0/fake-pass.webp"
          ]
        }
      }
    },
    {
      "id": "item_1xejV7puGeK_t",
      "detail": {
        "product": {
          "price": {
            "amount": 100,
            "currency": "JPY"
          },
          "quantity": 1,
          "label": "Diamond",
          "description": "",
          "images": [],
          "sku": "sku_103843dfjhdfgiu",
          "taxCategory": "VIRTUAL_CURRENCY"
        }
      }
    }
  ],
  "description": "Game items purchase",
  "reference": "ORDER_2024_001",
  "test": true,
  "expiresAt": "2024-12-31T23:59:59Z",
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:05:30Z"
}
```

### Order cancellation API

Cancel an existing order when you no longer want it to proceed. No request body is required—only the order ID in the path.

```bash
curl --request POST \
--url https://api.tokenz.one/v2/order/{YOUR_ORDER_ID}/cancel \
--header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
--header 'Content-Type: application/json'
```

**Response:**

```json
{
  "id": "order_1D5xA9BnKfv_t",
  "object": "order",
  "status": "canceled",
  "amount": {
    "amount": 3700,
    "currency": "JPY"
  },
  "items": [
    {
      "id": "item_1D6F8mR5TnK_t",
      "detail": {
        "product": {
          "price": {
            "amount": 1200,
            "currency": "JPY"
          },
          "quantity": 3,
          "label": "ひとにぎりのエメラルド",
          "description": "80+8",
          "images": [
            "https://images.ctfassets.net/z82qbo7cv7ia/1dWPbk5Qx2M1Qikj6Knyuc/e37b2c26829c0d30793a348ae3adb3b0/fake-pass.webp"
          ]
        }
      }
    },
    {
      "id": "item_1xejV7puGeK_t",
      "detail": {
        "product": {
          "price": {
            "amount": 100,
            "currency": "JPY"
          },
          "quantity": 1,
          "label": "Diamond",
          "description": "",
          "images": [],
          "sku": "sku_103843dfjhdfgiu",
          "taxCategory": "VIRTUAL_CURRENCY"
        }
      }
    }
  ],
  "description": "Game items purchase",
  "reference": "ORDER_2024_001",
  "test": true,
  "expiresAt": "2024-12-31T23:59:59Z",
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:05:30Z",
  "canceledAt": "2024-01-15T10:05:32Z"
}
```

If the order cannot be canceled (for example, because it has already succeeded), the API returns `422 Unprocessable Entity` with the error code `order.status-invalid`.

### Delivery registration API

Register delivery information for an order with payload flexibility. The API accepts any valid JSON structure and responds with warnings and suggestions to help you optimize your requests.

**Note**: This API supports multiple calls for the same order, enabling partial delivery tracking. For example, if an order contains multiple items delivered at different times, you can call this API once for each delivery. Each call creates an independent delivery record, allowing you to accurately track fulfillment progress.

```bash
curl --request POST \
--url https://api.tokenz.one/v2/order/{YOUR_ORDER_ID}/delivery \
--header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
--header 'Content-Type: application/json' \
--data '{
            "at": "2025-01-15T10:30:00Z",
            "user": {
              "userId": "user_67890",
              "phoneNumber": "+1234567890",
              "emailAddress": "test-user@example.com"
            },
            "items": [
              {
                "sku": "TEST-SKU-001",
                "name": "Test Product for Delivery",
                "itemId": "item_12345",
                "itemChange": {
                  "inAppBalanceAfter": 102,
                  "inAppBalanceBefore": 100
                },
                "deliveredQuantity": 2
              }
            ],
            "status": "succeeded",
            "metadata": {
              "customField": "test_value",
              "merchantNotes": "Successfully delivered via API",
              "deliveryChannel": "api"
            },
            "progress": "completed",
            "cartContext": {
              "deviceId": "device_abc123",
              "timestamp": "2025-01-15T10:00:00Z",
              "ipAddress": "192.168.1.100",
              "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
              "geoLocation": {
                "lat": 37.7749,
                "lon": -122.4194,
                "region": "US"
              }
            },
            "deliveryInfo": {
              "deliveryMethod": "digital_download",
              "confirmationType": "email",
              "confirmationProof": "delivery_confirmation_12345"
            },
            "deliveryContext": {
              "deviceId": "device_abc123",
              "timestamp": "2025-01-15T10:30:00Z",
              "ipAddress": "192.168.1.100",
              "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
            }
          }'
```

**Response:**

```json
{
  "success": true,
  "message": "Delivery record has been registered successfully"
}
```

The `warnings` and `suggestions` arrays are omitted from the response when empty. When present, they contain strings describing missing or suboptimal fields in your payload.

## API flexibility and guidance

The Delivery Registration API is designed with flexibility in mind - **you can submit any valid JSON structure**, and the API will accept it. However, to help you get the most value from your delivery tracking, the API provides warnings and suggestions in the response.

### Warning and suggestion system

When you register a delivery record, the API analyzes your payload and returns guidance:

- **Warnings**: Alert you to missing or invalid critical fields that are highly recommended for effective delivery tracking
- **Suggestions**: Recommend optional fields that can enhance analytics, fraud detection, and delivery optimization

This system allows you to start simple and gradually improve your integration based on the feedback provided.

### Field definitions and importance levels

#### Status and Progress Enums

**`status`**: Individual delivery status

- `succeeded` - This specific delivery was completed successfully
- `failed` - This specific delivery failed

**`progress`**: Overall order fulfillment progress

- `completed` - All items in the order have been fully delivered
- `in_progress` - Partial delivery - some items delivered, others pending
- `pending` - No items from the order have been delivered yet

**Important distinction**: For orders with multiple items that are delivered separately:

- `status` tracks each individual delivery transaction
- `progress` tracks the overall order fulfillment
- Example: An order with 3 items delivered in 2 separate transactions would have 2 delivery records (each with its own `status`), while `progress` reflects whether all 3 items have been delivered

#### Field Importance Categories

Fields are categorized by importance to help you prioritize your integration:

**Critical Fields** (generate warnings if missing/invalid):

- `status`: Delivery status (see enum values above)
- `progress`: Delivery progress (see enum values above)
- `at`: ISO 8601 timestamp of when the delivery occurred
- `cartContext.timestamp`: Timestamp within the cart context object, if `cartContext` is provided
- `deliveryContext.timestamp`: Timestamp within the delivery context object, if `deliveryContext` is provided

**Recommended Fields** (generate suggestions if missing):

- `items`: Array of delivered items with details
- `items[].deliveredQuantity`: Quantity of each item delivered
- `items[].itemChange.inAppBalanceBefore/After`: Critical for balance tracking
- `user`: User information for personalized insights
- `user.userId`: User identifier for delivery tracking
- `user.emailAddress`: User email for identification
- `deliveryContext`: Context information for fraud detection
- `deliveryInfo`: Delivery method and confirmation details

**Optional Fields** (no warnings, but valuable):

- `metadata`: Custom fields for your specific use case with type: Map<String, String>
- `cartContext`: Original purchase context
- Geographic location data

## Delivery record data structure

While the delivery record endpoint accepts any valid JSON structure, **we strongly recommend providing comprehensive delivery information** to protect your business in case of disputes. The more detailed your delivery records, the stronger your evidence if any issues arise.

As shown in the curl command example above, we recommend sending a complete payload with all available fields.

### Why comprehensive records matter for disputes

Providing complete delivery information is essential for dispute protection:

- **Evidence Documentation**: Detailed records serve as proof of delivery when customers raise disputes
- **Timeline Verification**: Timestamps and context data help establish when and how delivery occurred
- **Item Tracking**: Detailed item records prove exactly what was delivered and in what quantity

While the API will accept minimal data, incomplete records may leave you without sufficient evidence during disputes. Always include all available information to maintain a comprehensive audit trail.

## Response status codes

The Orders API returns standard HTTP status codes and detailed error messages:

- `200 OK`: Order retrieved or canceled successfully
- `201 Created`: Delivery record registered successfully
- `400 Bad Request`: Invalid request format or missing required fields
- `401 Unauthorized`: Invalid or missing API key
- `403 Forbidden`: Access denied to the requested resource
- `404 Not Found`: Order not found or access denied
- `422 Unprocessable Entity`: Action not allowed in the current order status (for example, canceling an already completed order returns `order.status-invalid`)
- `500 Server Error`: Internal server error

All error responses include a structured error object with code and message for programmatic handling.

### Error response example

```json
{
  "status": 404,
  "code": "entity.not-found",
  "message": "The requested order could not be found."
}
```

## Order webhooks

Configure webhooks to receive notifications about order events:

### `order.created`

Triggered when an order is created:

```json
{
  "id": "d4e5f6a7-b8c9-0123-defa-234567890abc",
  "object": "order.created",
  "createdAt": "2024-01-15T10:00:00Z",
  "test": true,
  "eventData": {
    "type": "order",
    "version": "v2",
    "data": {
      "order": {
        "id": "order_1D5xA9BnKfv_t",
        "object": "order",
        "status": "requiresPayment",
        "amount": {
          "amount": 3700,
          "currency": "JPY"
        },
        "consumerAmount": {
          "amount": 3700,
          "currency": "JPY"
        },
        "items": [
          {
            "id": "item_1D6F8mR5TnK_t",
            "detail": {
              "product": {
                "price": {
                  "amount": 3700,
                  "currency": "JPY"
                },
                "quantity": 1,
                "label": "Game Item Bundle",
                "description": "In-game items",
                "images": []
              }
            }
          }
        ],
        "description": "Game items purchase",
        "reference": "ORDER_2024_001",
        "test": true,
        "expiresAt": "2024-01-16T10:00:00Z",
        "createdAt": "2024-01-15T10:00:00Z",
        "updatedAt": "2024-01-15T10:00:00Z",
        "regionCode": "JP"
      }
    }
  }
}
```

### `order.succeeded`

Triggered when an order is successfully completed after payment:

```json
{
  "id": "e5f6a7b8-c9d0-1234-efab-345678901def",
  "object": "order.succeeded",
  "createdAt": "2024-01-15T10:45:00Z",
  "test": true,
  "eventData": {
    "type": "order",
    "version": "v2",
    "data": {
      "order": {
        "id": "order_1D5xA9BnKfv_t",
        "object": "order",
        "status": "succeeded",
        "amount": {
          "amount": 3700,
          "currency": "JPY"
        },
        "consumerAmount": {
          "amount": 3700,
          "currency": "JPY"
        },
        "items": [
          {
            "id": "item_1D6F8mR5TnK_t",
            "detail": {
              "product": {
                "price": {
                  "amount": 3700,
                  "currency": "JPY"
                },
                "quantity": 1,
                "label": "Game Item Bundle",
                "description": "In-game items",
                "images": []
              }
            }
          }
        ],
        "description": "Game items purchase",
        "reference": "ORDER_2024_001",
        "test": true,
        "expiresAt": "2024-01-16T10:00:00Z",
        "createdAt": "2024-01-15T10:00:00Z",
        "updatedAt": "2024-01-15T10:45:00Z",
        "regionCode": "JP"
      }
    }
  }
}
```

### `order.expired`

Triggered when an order reaches its expiry time without being completed:

```json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "object": "order.expired",
  "createdAt": "2024-12-31T23:59:59Z",
  "test": true,
  "eventData": {
    "type": "order",
    "version": "v2",
    "data": {
      "order": {
        "id": "order_1D5xA9BnKfv_t",
        "object": "order",
        "status": "expired",
        "amount": {
          "amount": 3700,
          "currency": "JPY"
        },
        "consumerAmount": {
          "amount": 3700,
          "currency": "JPY"
        },
        "items": [
          {
            "id": "item_1D6F8mR5TnK_t",
            "detail": {
              "product": {
                "price": {
                  "amount": 3700,
                  "currency": "JPY"
                },
                "quantity": 1,
                "label": "Game Item Bundle",
                "description": "In-game items",
                "images": []
              }
            }
          }
        ],
        "description": "Game items purchase",
        "reference": "ORDER_2024_001",
        "test": true,
        "expiresAt": "2024-12-31T23:59:59Z",
        "createdAt": "2024-01-15T10:00:00Z",
        "updatedAt": "2024-12-31T23:59:59Z",
        "regionCode": "JP"
      }
    }
  }
}
```

### `order.canceled`

Triggered when an order is canceled:

```json
{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "object": "order.canceled",
  "createdAt": "2024-01-15T10:05:32Z",
  "test": true,
  "eventData": {
    "type": "order",
    "version": "v2",
    "data": {
      "order": {
        "id": "order_1D5xA9BnKfv_t",
        "object": "order",
        "status": "canceled",
        "amount": {
          "amount": 3700,
          "currency": "JPY"
        },
        "consumerAmount": {
          "amount": 3700,
          "currency": "JPY"
        },
        "items": [
          {
            "id": "item_1D6F8mR5TnK_t",
            "detail": {
              "product": {
                "price": {
                  "amount": 3700,
                  "currency": "JPY"
                },
                "quantity": 1,
                "label": "Game Item Bundle",
                "description": "In-game items",
                "images": []
              }
            }
          }
        ],
        "description": "Game items purchase",
        "reference": "ORDER_2024_001",
        "test": true,
        "createdAt": "2024-01-15T10:00:00Z",
        "updatedAt": "2024-01-15T10:05:32Z",
        "canceledAt": "2024-01-15T10:05:32Z",
        "regionCode": "JP"
      }
    }
  }
}
```

### `order.failed`

Triggered when an order fails:

```json
{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "object": "order.failed",
  "createdAt": "2024-01-15T11:00:00Z",
  "test": true,
  "eventData": {
    "type": "order",
    "version": "v2",
    "data": {
      "order": {
        "id": "order_1D5xA9BnKfv_t",
        "object": "order",
        "status": "failed",
        "amount": {
          "amount": 3700,
          "currency": "JPY"
        },
        "consumerAmount": {
          "amount": 3700,
          "currency": "JPY"
        },
        "items": [
          {
            "id": "item_1D6F8mR5TnK_t",
            "detail": {
              "product": {
                "price": {
                  "amount": 3700,
                  "currency": "JPY"
                },
                "quantity": 1,
                "label": "Game Item Bundle",
                "description": "In-game items",
                "images": []
              }
            }
          }
        ],
        "description": "Game items purchase",
        "reference": "ORDER_2024_001",
        "test": true,
        "createdAt": "2024-01-15T10:00:00Z",
        "updatedAt": "2024-01-15T11:00:00Z",
        "regionCode": "JP"
      }
    }
  }
}
```

## Best practices

### Order and Delivery record management

- Store order IDs in your system for future reference
- Use webhooks to receive real-time order status updates
- Maintain independent delivery records and register them promptly after shipping or delivery. While our API provides backup storage for dispute resolution, your system should be the primary source of delivery data
- For partial deliveries, call the Delivery Registration API multiple times - once for each batch of items delivered. Each call creates a separate delivery record, enabling accurate tracking of multi-delivery orders

### Delivery Registration API integration strategy

- Use comprehensive payload structure to minimize warnings and maximize tracking capabilities
- Include all recommended fields (`at`, `user`, `items`, `deliveryContext`, `deliveryInfo`) for optimal performance
- Use ISO 8601 format for all timestamps (`at`, `cartContext.timestamp`, `deliveryContext.timestamp`) and make sure they are after 2024-03-01T00:00:00.000Z