Cancel an order

Request

Cancels an order.
Security
SecretApiKey or JWT
Bodyapplication/jsonrequired
Cancellation resource.
orderIdstring, <= 50 charactersrequired
ID of the canceled order.
Example:"sub_01HRF27SATGE4Z6PBJE6PD8328"
canceledBystring
Specifies who initiated the cancellation.
Default:"customer"
Enum:"merchant""customer""rebilly"
reasonstring

Reason for the cancellation.

The sandbox-retention value is set only in the sandbox environment when a recurring order is canceled 90 days after creation. If a request includes it, a validation error is returned.

Default:"other"
Enum:"did-not-use""did-not-want""missing-features""bugs-or-problems""do-not-remember""risk-warning""contract-expired""too-expensive""other""billing-failure"
descriptionstring, <= 255 characters
Description of the cancellation reason in free form.
proratedboolean

Specifies if the customer gets a pro rata credit for the time remaining between churnTime and order next renewal time.

Default:false
statusstring
Status of the order cancellation.
Default:"confirmed"
Enum ValueDescription
draft
Creates a draft cancellation so that the cancellation and charge can be previewed.
confirmed

Confirms an order cancellation. Sets the order to cancel when the churnTime is reached.

completed

Marks an order cancellation as completed. This is a read-only status that is set when the churnTime is reached. The cancellation may not be changed or deleted when the status is completed.

revoked
Revokes an order cancellation.
churnTimestring, (date-time)

Date and time when the order is deactivated. If this field and churnTimePolicy are omitted, this value defaults to the current time.

churnTimePolicystring or null

Specifies when the order is to be deactivated. The churnTimePolicy takes precedence over the churnTime in request.

Enum:null"now""at-next-renewal"
lineItemsArray of objects
Items to be added to the new invoice. Proration item is generated and added automatically.
curl -i -X POST \
  https://www.rebilly.com/_mock/catalog/all/order-cancellations \
  -H 'Content-Type: application/json' \
  -H 'REB-APIKEY: YOUR_API_KEY_HERE' \
  -d '{
    "orderId": "sub_01HRF27SATGE4Z6PBJE6PD8328",
    "canceledBy": "merchant",
    "reason": "did-not-use",
    "description": "string",
    "prorated": false,
    "status": "draft",
    "churnTime": "2019-08-24T14:15:22Z",
    "churnTimePolicy": null,
    "lineItems": [
      {
        "type": "debit",
        "description": "string",
        "unitPriceAmount": 49.95,
        "unitPriceCurrency": "USD",
        "quantity": 1,
        "periodStartTime": "2019-08-24T14:15:22Z",
        "periodEndTime": "2019-08-24T14:15:22Z"
      }
    ]
  }'

Responses

Cancellation created.
Headers
Locationstring, (uri)
Location of the related resource.
Example:"https://api.rebilly.com/example"
Rate-Limit-Limitinteger

Maximum number of requests available at one time for this rate limit. For more information, see Rate limits.

Example:500
Rate-Limit-Remaininginteger

Number of requests still available for this rate limit. For more information, see Rate limits.

Example:499
Bodyapplication/json
idstring, <= 50 charactersread-only
ID of the cancellation.
Example:"sub_cnl_0YVJ5XVQM9CDP8248ZQX0RDMKV"
orderIdstring, <= 50 charactersrequired
ID of the canceled order.
Example:"sub_01HRF27SATGE4Z6PBJE6PD8328"
proratedInvoiceIdstring or null, <= 50 charactersread-only
ID of the invoice on which the cancellation proration is calculated.
Example:"in_0YVF9605RKC62BP14NE2R7V2XT"
appliedInvoiceIdstring or null, <= 50 charactersread-only
ID of the invoice on which the cancellation fees or credits are applied.
Example:"in_0YVF9605RKC62BP14NE2R7V2XT"
canceledBystring
Specifies who initiated the cancellation.
Default:"customer"
Enum:"merchant""customer""rebilly"
reasonstring

Reason for the cancellation.

The sandbox-retention value is set only in the sandbox environment when a recurring order is canceled 90 days after creation. If a request includes it, a validation error is returned.

Default:"other"
Enum:"did-not-use""did-not-want""missing-features""bugs-or-problems""do-not-remember""risk-warning""contract-expired""too-expensive""other""billing-failure"
descriptionstring, <= 255 characters
Description of the cancellation reason in free form.
proratedboolean

Specifies if the customer gets a pro rata credit for the time remaining between churnTime and order next renewal time.

Default:false
statusstring
Status of the order cancellation.
Default:"confirmed"
Enum ValueDescription
draft
Creates a draft cancellation so that the cancellation and charge can be previewed.
confirmed

Confirms an order cancellation. Sets the order to cancel when the churnTime is reached.

completed

Marks an order cancellation as completed. This is a read-only status that is set when the churnTime is reached. The cancellation may not be changed or deleted when the status is completed.

revoked
Revokes an order cancellation.
canceledTimestring or null, (date-time)read-only

Date and time when an order is canceled. By default, this occurs when status is confirmed, unless draft is specified.

createdTimestring, (date-time)(CreatedTime)read-only
Date and time when the resource is created. This value is set automatically when the resource is created.
updatedTimestring, (date-time)(UpdatedTime)read-only
Date and time when the resource is updated. This value is set automatically when the resource is updated.
churnTimestring, (date-time)

Date and time when the order is deactivated. If this field and churnTimePolicy are omitted, this value defaults to the current time.

churnTimePolicystring or null

Specifies when the order is to be deactivated. The churnTimePolicy takes precedence over the churnTime in request.

Enum:null"now""at-next-renewal"
lineItemsArray of objects
Items to be added to the new invoice. Proration item is generated and added automatically.
lineItemSubtotalobjectread-only
Subtotal of the line items added after the order cancellation.
Response
{ "id": "sub_cnl_0YVJ5XVQM9CDP8248ZQX0RDMKV", "orderId": "sub_01HRF27SATGE4Z6PBJE6PD8328", "proratedInvoiceId": "in_0YVF9605RKC62BP14NE2R7V2XT", "appliedInvoiceId": "in_0YVF9605RKC62BP14NE2R7V2XT", "canceledBy": "merchant", "reason": "did-not-use", "description": "string", "prorated": false, "status": "draft", "canceledTime": "2019-08-24T14:15:22Z", "createdTime": "2019-08-24T14:15:22Z", "updatedTime": "2019-08-24T14:15:22Z", "churnTime": "2019-08-24T14:15:22Z", "churnTimePolicy": null, "lineItems": [ { … } ], "lineItemSubtotal": { "amount": 49.95, "currency": "USD" }, "_links": [ { … } ] }