Orders
Retrieve orders, cancel orders, and record what you deliver to the customer.
Amount format: All monetary values (such as amount fields) are expressed in the smallest minor unit of each currency. See Supported currencies for the exact encoding per currency.
Overview
Choose the task you need. Each API can be called independently:
| Task | Start here |
|---|---|
| Retrieve an order | Order retrieval API |
| Cancel an order | Order cancellation API |
| Register delivery | Delivery registration API |
| Handle order events | Order webhooks |
Order lifecycle
Orders automatically progress through different states as payments are processed:
- Order Creation: Orders are automatically created when merchants create checkout sessions
- Order Processing: Orders move through various states:
requiresPayment→processing→succeeded - Order Retrieval: Use our Orders API to access order details for fulfillment and tracking
- Delivery Registration: Independently register delivery information when orders are fulfilled
Order status values
Orders progress through the following status values:
| Status | Meaning |
|---|---|
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 |
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.
curl --request GET \
--url https://api.tokenz.one/v3/order/{YOUR_ORDER_ID} \
--header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
--header 'Content-Type: application/json'
Response:
Full response
{
"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",
"externalOrderId": "ORDER_2024_001",
"recipientId": "user_42931",
"metadata": {
"campaign": "spring_sale"
},
"test": true,
"expiresAt": "2024-12-31T23:59:59Z",
"createdAt": "2024-01-15T10:00:00Z",
"updatedAt": "2024-01-15T10:05:30Z"
}
recipientId is the account the order is for: credit the purchase to it, and send the same value as user.recipientId when you register a delivery. It is absent when the Checkout Session had no customerInfo.recipientId, which can happen under the Payment Gateway model. externalOrderId and metadata carry the values you set when creating the Checkout Session. metadata is absent when none was supplied, including on orders created for a subscription.
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.
curl --request POST \
--url https://api.tokenz.one/v3/order/{YOUR_ORDER_ID}/cancel \
--header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
--header 'Content-Type: application/json'
Response:
Full response
{
"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",
"externalOrderId": "ORDER_2024_001",
"recipientId": "user_42931",
"metadata": {
"campaign": "spring_sale"
},
"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.
Where it shows up: In the Merchant Dashboard, open the order from the Orders list. The order page lists every delivery record registered for it, with its payload.
curl --request POST \
--url https://api.tokenz.one/v3/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": {
"recipientId": "user_42931",
"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:
{
"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 successfullyfailed- This specific delivery failed
progress: Overall order fulfillment progress
completed- All items in the order have been fully deliveredin_progress- Partial delivery - some items delivered, others pendingpending- No items from the order have been delivered yet
Important distinction: For orders with multiple items that are delivered separately:
statustracks each individual delivery transactionprogresstracks 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), whileprogressreflects 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 occurredcartContext.timestamp: Timestamp within the cart context object, ifcartContextis provideddeliveryContext.timestamp: Timestamp within the delivery context object, ifdeliveryContextis provided
Recommended Fields (generate suggestions if missing):
items: Array of delivered items with detailsitems[].deliveredQuantity: Quantity of each item delivereditems[].itemChange.inAppBalanceBefore/After: Critical for balance trackinguser: User information for personalized insightsuser.recipientId: The order'srecipientId, identifying the account that received the deliveryuser.emailAddress: User email for identificationdeliveryContext: Context information for fraud detectiondeliveryInfo: 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 successfully201 Created: Delivery record registered successfully400 Bad Request: Invalid request format or missing required fields401 Unauthorized: Invalid or missing API key403 Forbidden: Access denied to the requested resource404 Not Found: Order not found or access denied422 Unprocessable Entity: Action not allowed in the current order status (for example, canceling an already completed order returnsorder.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
{
"status": 404,
"code": "entity.not-found",
"message": "The requested order could not be found."
}
Order webhooks
Use the event name to choose your handler. Expand an example for its complete payload.
| Event | When it is sent |
|---|---|
order.created | An order is created. |
order.succeeded | An order succeeds. |
order.expired | An order expires. |
order.canceled | An order is canceled. |
order.failed | An order fails. |
order.created
Triggered when an order is created:
Full payload: order.created
{
"id": "d4e5f6a7-b8c9-0123-defa-234567890abc",
"object": "order.created",
"createdAt": "2024-01-15T10:00:00Z",
"test": true,
"eventData": {
"type": "order",
"version": "v3",
"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",
"externalOrderId": "ORDER_2024_001",
"recipientId": "user_42931",
"metadata": {
"campaign": "spring_sale"
},
"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:
Full payload: order.succeeded
{
"id": "e5f6a7b8-c9d0-1234-efab-345678901def",
"object": "order.succeeded",
"createdAt": "2024-01-15T10:45:00Z",
"test": true,
"eventData": {
"type": "order",
"version": "v3",
"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",
"externalOrderId": "ORDER_2024_001",
"recipientId": "user_42931",
"metadata": {
"campaign": "spring_sale"
},
"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:
Full payload: order.expired
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"object": "order.expired",
"createdAt": "2024-12-31T23:59:59Z",
"test": true,
"eventData": {
"type": "order",
"version": "v3",
"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",
"externalOrderId": "ORDER_2024_001",
"recipientId": "user_42931",
"metadata": {
"campaign": "spring_sale"
},
"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:
Full payload: order.canceled
{
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"object": "order.canceled",
"createdAt": "2024-01-15T10:05:32Z",
"test": true,
"eventData": {
"type": "order",
"version": "v3",
"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",
"externalOrderId": "ORDER_2024_001",
"recipientId": "user_42931",
"metadata": {
"campaign": "spring_sale"
},
"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:
Full payload: order.failed
{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"object": "order.failed",
"createdAt": "2024-01-15T11:00:00Z",
"test": true,
"eventData": {
"type": "order",
"version": "v3",
"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",
"externalOrderId": "ORDER_2024_001",
"recipientId": "user_42931",
"metadata": {
"campaign": "spring_sale"
},
"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