Customer API Documentation

This documentation describes the API endpoints available for customers using our POD service. Note: Every request must include your API key in the HTTP header X-API-Key.

Base URL

All endpoints are available under:

https://pod.rrbindery.com

1. List Your Orders

Endpoint: GET /orders/

This endpoint returns a list of orders associated with your account. For non-admin customers, only orders created by your account are returned.

Headers:

Multi-line Example:

curl -X GET https://pod.rrbindery.com/orders/ \
  -H "X-API-Key: YOUR_API_KEY"

One-line Example:

curl -X GET https://pod.rrbindery.com/orders/ -H "X-API-Key: YOUR_API_KEY"

Response: A JSON array of order objects. Each order includes details such as:

2. Retrieve Order Details

Endpoint: GET /orders/<order_id>

Retrieve the full details for a specific order. You can only access orders that belong to your account.

Headers:

Multi-line Example:

curl -X GET https://pod.rrbindery.com/orders/ORDER_ID \
  -H "X-API-Key: YOUR_API_KEY"

One-line Example:

curl -X GET https://pod.rrbindery.com/orders/ORDER_ID -H "X-API-Key: YOUR_API_KEY"

Response: A JSON object with complete order details (including line items and file information).

3. Create a New Order

Endpoint: POST /orders/

This endpoint is used to submit a new order. Your API key automatically associates the order with your account.

Required JSON Field:

Optional/Additional Fields: You may include line item details and other order information. The server automatically sets or calculates the following fields:

Headers:

Multi-line Example:

curl -X POST https://pod.rrbindery.com/orders/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "your_order_external_id",
    "line_items": [
      {
        "id": "item1",
        "external_id": "item_external_id",
        "quantity": 2,
        "title": "Sample Book Title",
        "isbn": "1234567890123",
        "end_user_price": "15.99",
        "mono_pages": 10,
        "color_pages": 5,
        "pages": 150,
        "pod_package_id": "pod_package_code_if_applicable"
      }
    ]
  }'

One-line Example:

curl -X POST https://pod.rrbindery.com/orders/ -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" -d '{"external_id": "your_order_external_id", "line_items": [{"id": "item1", "external_id": "item_external_id", "quantity": 2, "title": "Sample Book Title", "isbn": "1234567890123", "end_user_price": "15.99", "mono_pages": 10, "color_pages": 5, "pages": 150, "pod_package_id": "pod_package_code_if_applicable"}]}'

Response: On success, the API returns a JSON object similar to:

{
  "status": "Order Created",
  "order_id": "generated_order_id",
  "rr_job_number": 12345,
  "ship_date": "YYYY-MM-DD"
}

If an order with the same external_id already exists for your account, a 409 Conflict error is returned with the existing order details.

4. Mark File as Downloaded

Endpoint: POST /orders/<order_id>/line_items/<line_item_id>/files/<file_index>/mark_downloaded

This endpoint allows you to mark a file (associated with a line item) as downloaded. You can only update files for orders that belong to your account.

Parameters:

Headers:

Optional JSON Body: You may include a downloaded_at field to specify a custom timestamp. If omitted, the current UTC timestamp is used.

Multi-line Example:

curl -X POST https://pod.rrbindery.com/orders/ORDER_ID/line_items/LINE_ITEM_ID/files/0/mark_downloaded \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "downloaded_at": "2025-02-05T12:34:56Z" }'

One-line Example:

curl -X POST https://pod.rrbindery.com/orders/ORDER_ID/line_items/LINE_ITEM_ID/files/0/mark_downloaded -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" -d '{ "downloaded_at": "2025-02-05T12:34:56Z" }'

Response: A successful response will look like:

{
  "status": "ok",
  "downloaded_at": "2025-02-05T12:34:56Z"
}

Error Handling

In the event of errors, the API will return standard HTTP status codes along with a JSON error message. Common responses include:

Additional Notes