Update & Cancel Orders

Manage existing orders by updating expiration dates or canceling access entirely.

---

Update Order

Update the expiration date for all products in an order. This is useful for extending or limiting access periods.

Endpoint

PUT /api/v3/orders/{order_id}

Path Parameters

Parameter	Type	Description
order_id	string	Order UUID or external reference

Query Parameters

Parameter	Type	Default	Description
id_type	string	internal	internal for UUID, external for external reference
include	string	-	Comma-separated: user, products, pending_checkout
fields	string	-	Comma-separated list of fields to return

Request Body

Field	Type	Description	Required
expiration_date	string	New expiration date (YYYY-MM-DD)	Required if status not provided
status	string	New order status: paused or approved	Required if expiration_date not provided

Status Updates

The status field can only be updated for subscription orders created with a manual gateway (external payment). Attempting to update status on non-subscription orders will return a 422 error.

---

Update Examples

Update by Internal UUID

curl -X PUT "https://yourstore.publica.la/api/v3/orders/275ca6c4-a815-4f64-8198-759a296dd495" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "expiration_date": "2026-12-31"
  }'

Update by External Reference

curl -X PUT "https://yourstore.publica.la/api/v3/orders/MY-ORDER-123?id_type=external" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "expiration_date": "2026-12-31"
  }'

Extend Access

# Extend subscription access by one year
curl -X PUT "https://yourstore.publica.la/api/v3/orders/SUBSCRIPTION-001?id_type=external" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "expiration_date": "2027-12-31"
  }'

---

Update Response

Success Response (200 OK)

{
  "data": {
    "id": "12345",
    "uuid": "275ca6c4-a815-4f64-8198-759a296dd495",
    "external_id": "MY-ORDER-123",
    "type": "permission",
    "status": "approved",
    "unit_price": 29.99,
    "currency_id": "USD",
    "created_at": "2025-12-03T22:43:44.000000Z",
    "updated_at": "2025-12-03T23:15:22.000000Z"
  }
}

Response with Includes

Request with ?include=user,products:

{
  "data": {
    "id": "12345",
    "uuid": "275ca6c4-a815-4f64-8198-759a296dd495",
    "external_id": "MY-ORDER-123",
    "type": "permission",
    "status": "approved",
    "unit_price": 29.99,
    "currency_id": "USD",
    "created_at": "2025-12-03T22:43:44.000000Z",
    "updated_at": "2025-12-03T23:15:22.000000Z",
    "user": {
      "id": "67890",
      "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "external_id": "user-123",
      "email": "[email protected]"
    },
    "products": [
      {
        "id": "54321",
        "external_id": "9781234567890",
        "type": "content",
        "name": "Digital Marketing Handbook",
        "status": "approved",
        "expiration_date": "2026-12-31",
        "unit_price": 29.99,
        "currency_id": "USD",
        "cover_url": "https://cdn.publica.la/covers/book.jpg",
        "reader_url": "https://yourstore.publica.la/reader/digital-marketing",
        "product_url": "https://yourstore.publica.la/library/publication/digital-marketing"
      }
    ]
  }
}

All Products Updated

The expiration date update applies to all products in the order. You cannot update individual product expirations.

---

Cancel Order (Delete)

Cancel an order and revoke user access to all products.

Endpoint

DELETE /api/v3/orders/{order_id}

Path Parameters

Parameter	Type	Description
order_id	string	Order UUID or external reference

Query Parameters

Parameter	Type	Default	Description
id_type	string	internal	internal for UUID, external for external reference

Request Body (Optional)

Field	Type	Description	Required
reason	string	Cancellation reason (3-150 chars)	No
expiration_date	string	Effective cancellation date (YYYY-MM-DD)	No

---

Cancel Examples

Immediate Cancellation

curl -X DELETE "https://yourstore.publica.la/api/v3/orders/275ca6c4-a815-4f64-8198-759a296dd495" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Customer requested refund"
  }'

Cancel by External Reference

curl -X DELETE "https://yourstore.publica.la/api/v3/orders/MY-ORDER-123?id_type=external" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Subscription not renewed"
  }'

Scheduled Cancellation

Set a future date when access will be revoked:

curl -X DELETE "https://yourstore.publica.la/api/v3/orders/275ca6c4-a815-4f64-8198-759a296dd495" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Subscription ending at period end",
    "expiration_date": "2025-12-31"
  }'

Cancel Without Reason

curl -X DELETE "https://yourstore.publica.la/api/v3/orders/275ca6c4-a815-4f64-8198-759a296dd495" \
  -H "X-User-Token: your-api-token"

---

Cancel Response

Success Response (200 OK)

{
  "data": {
    "id": "12345",
    "uuid": "275ca6c4-a815-4f64-8198-759a296dd495",
    "external_id": "MY-ORDER-123",
    "type": "permission",
    "status": "cancelled",
    "unit_price": 29.99,
    "currency_id": "USD",
    "created_at": "2025-12-03T22:43:44.000000Z",
    "updated_at": "2025-12-03T23:30:15.000000Z"
  }
}

Scheduled Cancellation Response

When using expiration_date, the order remains active until that date:

{
  "data": {
    "id": "12345",
    "uuid": "275ca6c4-a815-4f64-8198-759a296dd495",
    "external_id": "MY-ORDER-123",
    "type": "permission",
    "status": "approved",
    "unit_price": 29.99,
    "currency_id": "USD",
    "created_at": "2025-12-03T22:43:44.000000Z",
    "updated_at": "2025-12-03T23:30:15.000000Z"
  }
}

Scheduled Cancellations

When you provide an expiration_date, the order remains approved until that date. Access is automatically revoked when the date passes.

---

Error Handling

Order Not Found (404)

{
  "message": "Order not found."
}

Invalid Expiration Date (422)

{
  "message": "The given data was invalid.",
  "errors": {
    "expiration_date": ["The expiration_date must be a valid date."]
  }
}

Status Update Not Allowed (422)

{
  "message": "The given data was invalid.",
  "errors": {
    "status": ["Status updates are only allowed for subscription orders."]
  }
}

Invalid Reason Length (422)

{
  "message": "The given data was invalid.",
  "errors": {
    "reason": ["The reason must be between 3 and 150 characters."]
  }
}

Order Already Cancelled (422)

{
  "message": "The given data was invalid.",
  "errors": {
    "order": ["Order is already cancelled."]
  }
}

---

Common Error Causes

Error	Cause
Order not found	UUID doesn't exist or wrong id_type
Invalid date format	Date not in YYYY-MM-DD format
Status update not allowed	Trying to update status on non-subscription order
Reason too short	Reason less than 3 characters
Reason too long	Reason exceeds 150 characters
Order already cancelled	Attempting to cancel a cancelled order

---

Use Cases

Subscription Renewal

Extend access when subscription is renewed:

curl -X PUT "https://yourstore.publica.la/api/v3/orders/SUB-12345?id_type=external" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "expiration_date": "2026-12-31"
  }'

Refund Processing

Immediately revoke access after refund:

curl -X DELETE "https://yourstore.publica.la/api/v3/orders/ORDER-789?id_type=external" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Full refund issued - order #789"
  }'

Grace Period Cancellation

Allow access until end of billing period:

curl -X DELETE "https://yourstore.publica.la/api/v3/orders/SUB-12345?id_type=external" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Subscription cancelled by user",
    "expiration_date": "2025-12-31"
  }'

Corporate Access Revocation

Revoke employee access when they leave:

curl -X DELETE "https://yourstore.publica.la/api/v3/orders/CORP-EMP-123?id_type=external" \
  -H "X-User-Token: your-api-token" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Employee offboarding"
  }'

---

Best Practices

1. Store External References

Always use meaningful external_id values for easy lookup:

{
  "external_id": "STRIPE-SUB-cus_ABC123"
}

2. Log Cancellation Reasons

Provide descriptive reasons for audit trails:

{
  "reason": "Refund #12345 - customer complaint"
}

3. Use Scheduled Cancellations

For subscriptions, schedule cancellations at period end:

{
  "reason": "User cancelled subscription",
  "expiration_date": "2025-12-31"
}

4. Verify After Update

Retrieve the order after update to confirm changes:

curl -X GET "https://yourstore.publica.la/api/v3/orders/275ca6c4...?include=products" \
  -H "X-User-Token: your-api-token"

---

See Also

• Get Order - Retrieve order details
• List Orders - Query orders
• Permission Orders - Create permission orders
• Report Orders - Create report orders

---