NAV

English | Polski

Introduction

The Flexible Subscriptions REST API allows you to view, update, and delete subscriptions using requests in JSON format. It is fully integrated with the WordPress REST API.

This documentation is for v3 of the REST API, which is the current version.

WooCommerce Subscriptions (WCS) Compatibility

The Flexible Subscriptions REST API is designed to be largely compatible with the official WooCommerce Subscriptions (WCS) REST API. This means:

This compatibility allows you to easily migrate existing WCS REST API integrations or use existing WCS REST API client libraries with minimal changes.

Authentication

To use the REST API, you must authenticate. This is done using the standard WooCommerce REST API authentication methods.

Please refer to the official WooCommerce guide on generating REST API keys and authentication.

Enhanced WooCommerce API with Subscription Data

The Flexible Subscriptions plugin enhances the standard WooCommerce REST API with subscription-related data and functionality, making it seamless to work with subscriptions alongside regular WooCommerce operations.

Subscription Creation via Orders API

Subscriptions are not created directly via a POST request to the /subscriptions endpoint. Instead, a subscription is created automatically when an order is created that contains a subscription product.

To create a subscription, you should make a request to the standard WooCommerce Orders API endpoint.

POST /wp-json/wc/v3/orders

Include a subscription product in the line_items of your request. Once the order is processed (e.g., paid), the associated subscription will be generated.

Example of creating an order that will generate a subscription:

{
  "payment_method": "bacs",
  "payment_method_title": "Direct Bank Transfer",
  "set_paid": true,
  "billing": {
    "first_name": "John",
    "last_name": "Doe",
    "address_1": "969 Market",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US",
    "email": "john.doe@example.com",
    "phone": "(555) 555-5555"
  },
  "line_items": [
    {
      "product_id": 123,
      "quantity": 1
    }
  ],
  "shipping_lines": [
    {
      "method_id": "flat_rate",
      "method_title": "Flat Rate",
      "total": "10.00"
    }
  ]
}

For more details, please see the Create an order section in the WooCommerce REST API documentation.

Enhanced Orders Response with Subscriptions

When creating orders through the standard WooCommerce Orders API, the response will include a subscriptions array containing the IDs of any subscriptions created as a result of the order.

Enhanced Order Properties

Attribute Type Description
subscriptions array Array of subscription IDs created from this order. Always included in the response. read-only

Example Order Response with Subscriptions

{
  "id": 1230,
  "status": "completed",
  "total": "35.00",
  "date_created": "2024-06-10T10:00:00",
  "subscriptions": [1234],
  "..." : "..."
}

Subscriptions

The Subscriptions API allows you to view, update, and delete individual subscriptions.

Subscription Properties

Attribute Type Description
id integer Unique identifier for the resource. read-only
parent_id integer The ID of the initial order used to create the subscription. read-only
status string Subscription status. Options: pending, active, on-hold, pending-cancel, cancelled, expired.
currency string Currency the subscription was created with, in ISO format.
date_created date-time The date the subscription was created, in the site's timezone. read-only
date_created_gmt date-time The date the subscription was created, as GMT. read-only
date_modified date-time The date the subscription was last modified, in the site's timezone. read-only
date_modified_gmt date-time The date the subscription was last modified, as GMT. read-only
start_date_gmt date-time The subscription's start date in GMT. Must be in the format YYYY-mm-dd H:i:s.
trial_end_date_gmt date-time The subscription's trial end date in GMT. Must be in the format YYYY-mm-dd H:i:s.
next_payment_date_gmt date-time The subscription's next payment date in GMT. Must be in the format YYYY-mm-dd H:i:s.
end_date_gmt date-time The subscription's end date in GMT. Must be in the format YYYY-mm-dd H:i:s.
cancelled_date_gmt date-time The date the subscription was cancelled in GMT. read-only
total string Grand total for each renewal. read-only
customer_id integer User ID who owns the subscription.
billing object Billing address. See Order - Billing properties.
shipping object Shipping address. See Order - Shipping properties.
payment_method string Payment method ID.
payment_method_title string Payment method title.
customer_note string Note left by customer during checkout.
billing_period string The subscription's billing period. Options: D (Day), W (Week), M (Month), and Y (Year).
billing_interval integer The number of billing periods between subscription renewals (e.g., for a billing period of M and interval of 2, the subscription renews every 2 months).
meta_data array Meta data. See Order - Meta data properties.
line_items array Line items data. See Order - Line items properties.
tax_lines array Tax lines data. See Order - Tax lines properties. read-only
shipping_lines array Shipping lines data. See Order - Shipping lines properties.
fee_lines array Fee lines data. See Order - Fee lines properties.
coupon_lines array Coupons line data. See Order - Coupon lines properties.

Retrieve a Subscription

This API retrieves a specific subscription by its ID.

HTTP Request

GET /wp-json/wc/v3/subscriptions/<id>

curl https://example.com/wp-json/wc/v3/subscriptions/1234 \
    -u consumer_key:consumer_secret

JSON response example:

{
  "id": 1234,
  "parent_id": 1230,
  "status": "active",
  "currency": "USD",
  "date_created": "2024-06-10T10:00:00",
  "date_created_gmt": "2024-06-10T14:00:00",
  "date_modified": "2024-06-10T10:05:00",
  "date_modified_gmt": "2024-06-10T14:05:00",
  "start_date_gmt": "2024-06-10T14:00:00",
  "trial_end_date_gmt": null,
  "next_payment_date_gmt": "2024-07-10T14:00:00",
  "end_date_gmt": null,
  "cancelled_date_gmt": null,
  "total": "25.00",
  "customer_id": 1,
  "billing": {
    "first_name": "John",
    "last_name": "Doe",
    "address_1": "969 Market",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US",
    "email": "john.doe@example.com",
    "phone": "(555) 555-5555"
  },
  "shipping": {
    "first_name": "John",
    "last_name": "Doe",
    "address_1": "969 Market",
    "city": "San Francisco",
    "state": "CA",
    "postcode": "94103",
    "country": "US"
  },
  "payment_method": "stripe",
  "payment_method_title": "Credit Card (Stripe)",
  "customer_note": "",
  "billing_period": "M",
  "billing_interval": 1,
  "meta_data": [],
  "line_items": [
    {
      "id": 5,
      "name": "Monthly Coffee Box",
      "product_id": 123,
      "quantity": 1,
      "total": "25.00"
    }
  ],
  "tax_lines": [],
  "shipping_lines": [],
  "fee_lines": [],
  "coupon_lines": [],
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wc/v3/subscriptions/1234"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wc/v3/subscriptions"
      }
    ],
    "customer": [
      {
        "href": "https://example.com/wp-json/wc/v3/customers/1"
      }
    ],
    "orders": [
      {
        "href": "https://example.com/wp-json/wc/v3/subscriptions/1234/orders"
      }
    ]
  }
}

List all Subscriptions

This API retrieves all subscriptions, with support for pagination and filtering.

HTTP Request

GET /wp-json/wc/v3/subscriptions

curl https://example.com/wp-json/wc/v3/subscriptions?customer=1 \
    -u consumer_key:consumer_secret

Available Parameters

Parameter Type Description
context string Scope under which the request is made; determines fields present in response. Options: view and edit. Default is view.
page integer Current page of the collection. Default is 1.
per_page integer Maximum number of items to be returned in result set. Default is 10.
search string Limit results to those matching a string in the billing or shipping address.
after string Limit response to resources created after a given ISO8601 compliant date.
before string Limit response to resources created before a given ISO8601 compliant date.
status array Limit result set to subscriptions assigned a specific status. Options: any, pending, active, on-hold, pending-cancel, cancelled, expired. Default is any.
customer integer Limit result set to subscriptions assigned a specific customer ID.
product integer Limit result set to subscriptions containing a specific product ID.
order string Order sort attribute ascending or descending. Options: asc and desc. Default is desc.
orderby string Sort collection by object attribute. Options: date, id, include, modified. Default is date.

Update a Subscription

This API allows you to make changes to a subscription.

HTTP Request

PUT /wp-json/wc/v3/subscriptions/<id>

curl -X PUT https://example.com/wp-json/wc/v3/subscriptions/1234 \
    -u consumer_key:consumer_secret \
    -H "Content-Type: application/json" \
    -d '{
  "status": "on-hold"
}'

JSON response example:

{
  "id": 1234,
  "status": "on-hold",
  "date_modified": "2024-06-10T11:30:00",
  "date_modified_gmt": "2024-06-10T15:30:00",
  "...": "..."
}

Delete a Subscription

This API allows you to delete a subscription.

HTTP Request

DELETE /wp-json/wc/v3/subscriptions/<id>

curl -X DELETE https://example.com/wp-json/wc/v3/subscriptions/1234?force=true \
    -u consumer_key:consumer_secret

Available Parameters

Parameter Type Description
force boolean Whether to permanently delete the subscription. Default is false.

Subscription Orders

The subscription orders API allows you to view orders related to a specific subscription, such as the initial parent order and subsequent renewal orders.

Subscription Order Properties

Subscription orders have the same properties as standard WooCommerce orders. Please refer to the Order properties in the main WooCommerce REST API documentation.

In addition, each order will have enhanced relationship information and subscription references.

Attribute Type Description
subscription_id integer The ID of the subscription this order is related to. Present for both original and renewal orders. read-only
subscription_relationship string The relationship type of this order to the subscription. Options: original, renewal, switch, resubscribe. read-only
meta_data array An array of meta data. Will contain an entry with key = _fsb_order_type and value corresponding to the relationship type for backward compatibility.

List Subscription Orders

This API retrieves all orders related to a specific subscription.

HTTP Request

GET /wp-json/wc/v3/subscriptions/<id>/orders

curl https://example.com/wp-json/wc/v3/subscriptions/1234/orders \
    -u consumer_key:consumer_secret

JSON response example:

[
  {
    "id": 1235,
    "parent_id": 1234,
    "status": "completed",
    "total": "25.00",
    "date_created": "2024-07-10T10:00:00",
    "subscription_id": 1234,
    "subscription_relationship": "renewal",
    "meta_data": [
      {
        "id": 987,
        "key": "_fsb_order_type",
        "value": "renewal"
      }
    ],
    "..." : "..."
  },
  {
    "id": 1230,
    "parent_id": 0,
    "status": "completed",
    "total": "35.00",
    "date_created": "2024-06-10T10:00:00",
    "subscription_id": 1234,
    "subscription_relationship": "original",
    "..." : "..."
  }
]

Subscription Notes

The subscription notes API allows you to create, view, and delete individual subscription notes. Subscription notes are added by administrators and programmatically to store data about a subscription, or to record a subscription event.

Subscription Note Properties

Attribute Type Description
id integer Unique identifier for the resource. read-only
author string Subscription note author. read-only
date_created date-time The date the subscription note was created, in the site's timezone. read-only
date_created_gmt date-time The date the subscription note was created, as GMT. read-only
note string Subscription note. required
customer_note boolean If true, the note will be shown to customers and they will be notified. If false, the note will be for admin reference only. Default is false.
added_by_user boolean If true, this note will be attributed to the current user. If false, the note will be attributed to the system. Default is false.

Create a Subscription Note

This API helps you to create a new note for a subscription.

HTTP Request

POST /wp-json/wc/v3/subscriptions/<id>/notes

curl -X POST https://example.com/wp-json/wc/v3/subscriptions/1275/notes \
    -u consumer_key:consumer_secret \
    -H "Content-Type: application/json" \
    -d '{
  "note": "Example subscription note."
}'

JSON response example:

{
    "id": 2807,
    "author": "WooCommerce",
    "date_created": "2021-04-22T13:51:07",
    "date_created_gmt": "2021-04-22T03:51:07",
    "note": "Example subscription note.",
    "customer_note": false,
    "_links": {
        "self": [
            {
                "href": "https://example.com/wp-json/wc/v3/subscriptions/1275/notes/2807"
            }
        ],
        "collection": [
            {
                "href": "https://example.com/wp-json/wc/v3/subscriptions/1275/notes"
            }
        ],
        "up": [
            {
                "href": "https://example.com/wp-json/wc/v3/subscriptions/1275"
            }
        ]
    }
}

Retrieve a Subscription Note

This API lets you retrieve and view a specific note from a subscription.

HTTP Request

GET /wp-json/wc/v3/subscriptions/<id>/notes/<note_id>

curl https://example.com/wp-json/wc/v3/subscriptions/1275/notes/2807 \
    -u consumer_key:consumer_secret

JSON response example:

{
    "id": 2807,
    "author": "WooCommerce",
    "date_created": "2021-04-22T13:51:07",
    "date_created_gmt": "2021-04-22T03:51:07",
    "note": "Example subscription note.",
    "customer_note": false,
    "_links": {
        "self": [
            {
                "href": "https://example.com/wp-json/wc/v3/subscriptions/1275/notes/2807"
            }
        ],
        "collection": [
            {
                "href": "https://example.com/wp-json/wc/v3/subscriptions/1275/notes"
            }
        ],
        "up": [
            {
                "href": "https://example.com/wp-json/wc/v3/subscriptions/1275"
            }
        ]
    }
}

List all Subscription Notes

This API retrieves all the notes from a subscription.

HTTP Request

GET /wp-json/wc/v3/subscriptions/<id>/notes

curl https://example.com/wp-json/wc/v3/subscriptions/1275/notes \
    -u consumer_key:consumer_secret

JSON response example:

[
    {
        "id": 2716,
        "author": "WooCommerce",
        "date_created": "2021-04-19T17:21:00",
        "date_created_gmt": "2021-04-19T07:21:00",
        "note": "Payment status marked complete.",
        "customer_note": false,
        "_links": {
            "self": [
                {
                    "href": "https://example.com/wp-json/wc/v3/subscriptions/1275/notes/2716"
                }
            ],
            "collection": [
                {
                    "href": "https://example.com/wp-json/wc/v3/subscriptions/1275/notes"
                }
            ],
            "up": [
                {
                    "href": "https://example.com/wp-json/wc/v3/subscriptions/1275"
                }
            ]
        }
    },
    {
        "id": 2717,
        "author": "WooCommerce",
        "date_created": "2021-04-19T17:21:00",
        "date_created_gmt": "2021-04-19T07:21:00",
        "note": "Status changed from Pending to Active.",
        "customer_note": false,
        "_links": {
            "self": [
                {
                    "href": "https://example.com/wp-json/wc/v3/subscriptions/1275/notes/2717"
                }
            ],
            "collection": [
                {
                    "href": "https://example.com/wp-json/wc/v3/subscriptions/1275/notes"
                }
            ],
            "up": [
                {
                    "href": "https://example.com/wp-json/wc/v3/subscriptions/1275"
                }
            ]
        }
    }
]

Delete a Subscription Note

This API deletes a subscription note.

HTTP Request

DELETE /wp-json/wc/v3/subscriptions/<id>/notes/<note_id>

curl -X DELETE https://example.com/wp-json/wc/v3/subscriptions/1275/notes/2716?force=true \
    -u consumer_key:consumer_secret

Available Parameters

Parameter Type Description
force boolean Whether to permanently delete the note. Default is false.

JSON response example:

{
    "id": 2716,
    "author": "WooCommerce",
    "date_created": "2021-04-19T17:21:00",
    "date_created_gmt": "2021-04-19T07:21:00",
    "note": "Payment status marked complete.",
    "customer_note": false,
    "_links": {
        "self": [
            {
                "href": "https://example.com/wp-json/wc/v3/subscriptions/1275/notes/2716"
            }
        ],
        "collection": [
            {
                "href": "https://example.com/wp-json/wc/v3/subscriptions/1275/notes"
            }
        ],
        "up": [
            {
                "href": "https://example.com/wp-json/wc/v3/subscriptions/1275"
            }
        ]
    }
}