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 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:

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:

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

Diagram

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