Product

Page number for pagination

Defaults to 1.

Items per page

Defaults to 10.

Filter by product type

Possible values: one_time, subscription.

List of relations to expand in the response. Each expandable field on the response schema names its key, e.g. expand[]=customer. Nested keys use dot notation, e.g. items.product or subscriptions.items. Fields marked as always present are returned without being requested. An expanded list is null, not [], when there are no records. Unknown keys are ignored unless the endpoint says otherwise.

Field to sort by. Required whenever any sort[...] key is present, so sending sort[direction] on its own returns 422. Send sort as an object (sort[field]=name), never as a scalar. When sort is omitted the list is ordered by id descending.

Possible values: id, name.

Sort direction; defaults to asc.

Possible values: asc, desc.

Defaults to "asc".

A query parameter fails validation. type is not one_time or subscription; ids[], tags[] or slugs[] is not an array of unique values (ids[] integers, tags up to 255 characters, slugs up to 80); published, digital or gift_card is not a boolean; page is below 1; per_page is outside 1 to 100; sort is not an object, sort[field] is missing or not id or name, or sort[direction] is not asc or desc; or expand is not an array.

List of relations to expand in the response. Each expandable field on the response schema names its key, e.g. expand[]=customer. Nested keys use dot notation, e.g. items.product or subscriptions.items. Fields marked as always present are returned without being requested. An expanded list is null, not [], when there are no records. Unknown keys are ignored unless the endpoint says otherwise.

List of relations to expand in the response. Each expandable field on the response schema names its key, e.g. expand[]=customer. Nested keys use dot notation, e.g. items.product or subscriptions.items. Fields marked as always present are returned without being requested. An expanded list is null, not [], when there are no records. Unknown keys are ignored unless the endpoint says otherwise.

The variant is archived (entity_archived).

expand is not an array.

Prohibited for gift card products. A product cannot have more than 3 distinct option types in total, counting option types already used by its variants.

The variant or its parent product is archived (entity_archived).

A body field fails validation. name is over 255 characters, or is sent empty for a gift card variant that has no name yet; price is not a non-negative integer; inventory_item_id is not a non-archived inventory item of the shop; options.create has more than 3 entries or an entry without name or value; an options.update entry has no id or value. On gift card products inventory_item_id and options are prohibited ('Inventory item is not available for gift card products.', 'Options are not available for gift card products.'). Other messages: 'A product cannot have more than 3 option types.', "Option type '' does not exist on this product." and 'This option does not belong to this variant.'

List of relations to expand in the response. Each expandable field on the response schema names its key, e.g. expand[]=customer. Nested keys use dot notation, e.g. items.product or subscriptions.items. Fields marked as always present are returned without being requested. An expanded list is null, not [], when there are no records. Unknown keys are ignored unless the endpoint says otherwise.

The plan is archived (entity_archived), or its product belongs to a bundle (product_in_bundle).

expand is not an array, or one of its values is not a string.

Required when the plan's shipment schedule is anchored (entries with unit_day), and prohibited when it is not. If shipment_schedule is sent in the same request, that value decides; otherwise the stored schedule does.

Format HH:mm. Defaults to "23:59" when cut_off_days is sent without it. Rejected for digital products, for non-anchored shipment schedules, and when the shop's subscription plan does not include the cut-off-time feature.

Prohibited for digital products. Must be 1 when the plan is ad-hoc (no rebilling_day, rebilling_day_of_month or rebilling_day_of_week stored). Required whenever ship_immediately is sent.

Possible values: 0, 1.

Required whenever charge_immediately is sent. Cannot be 1 while charge_immediately is 0, and cannot be set to 0 while the plan has buffer_days; send buffer_days as null in the same request to clear it.

Possible values: 0, 1.

Only settable when the plan has exactly one shipment schedule entry, counted from shipment_schedule if sent in the same request, otherwise from the plan's stored schedule.

Prohibited when the parent product has a pre-order end date, and prohibited for anchored plans (plans with a stored rebilling_day* value).

Prohibited when the parent product has a pre-order end date, and prohibited for anchored plans (plans with a stored rebilling_day* value).

Prohibited for digital products. Setting it to 1 also requires an ad-hoc plan with a trial length (sent or already stored) and no pre-order end date.

Possible values: 0, 1.

Only available when the shop's subscription plan includes commitment billing.

Prohibited for digital products. All entries must use the same format, and each entry must supply exactly one of the two pairs: buffered (add_unit + add_count) or anchored (unit_day + unit_offset). The buffered pair is prohibited while the plan's schedule is anchored.

The plan or its product is archived (entity_archived), or the product belongs to a bundle (product_in_bundle).

A body field fails validation. Common cases: price changes while the plan has active subscriptions ('The price field cannot be changed while there are active subscriptions.'); cut_off_days is sent for a non-anchored shipment schedule, is empty for an anchored one, or is out of range; cut_off_time is not HH:mm, or is sent for a digital product, a non-anchored schedule, or a shop whose plan lacks the cut-off-time feature; charge_immediately is not 1 on an ad-hoc plan or is sent for a digital product; ship_immediately is 1 while charge_immediately is 0, or is 0 while buffer days are set; buffer_days is out of range, is set while ship immediately is off, or is set with more than one shipment entry; trial fields are sent on an anchored plan or a pre-order product; commitment_billing_count is sent without the plan feature; shipment_schedule is sent for a digital product, mixes anchored and buffered entries, or has values out of range; survey_id is not a survey of the shop.

Possible values: 0, 1.

Not available for digital products: when digital is 1 the only accepted value is 0. Defaults to 0 when omitted.

Possible values: 0, 1.

Date in Y-m-d form; must be today or later. Must be omitted when digital is 1; pre-order is not available for digital products.

Format: date.

Disabling pause (0) requires the optional-pause feature on the shop's plan. Shops without it may only send 1. Defaults to 1 when omitted.

Possible values: 0, 1.

Only digital products (digital: 1) may send 0. For physical products the only accepted value is 1. Defaults to 1 for physical products and 0 for digital ones when omitted.

Possible values: 0, 1.

A body field fails validation. name or slug is missing; slug has characters other than letters, digits, dashes and underscores, is over 80 characters, or is already used by a product of the shop; gifting_enabled is 1 on a digital product ('Gifting is not available for digital products.'); pre_order_end_at is not Y-m-d, is before today, or is sent for a digital product; pause_enabled is 0 and the shop plan lacks optional pause; collect_shipping_address is 0 on a physical product ('Collect shipping address is only available for digital products.'); tax_product_code is sent by a shop outside the US ('Tax product code is only available for US-based shops.'); inventory_item_id or funnel_id does not belong to the shop; tags.create values repeat or are over 255 characters; or images.create has more than 5 entries or an entry without a valid url.

Must be omitted for digital products; sending any value, including 0, on a digital product is rejected with 422.

Possible values: 0, 1.

Date in Y-m-d form; must be today or later. Must be omitted for digital products. Rejected with 422 when any active plan of this product has a trial; remove the trial first, or send null to clear the pre-order date.

Format: date.

Disabling pause (0) requires the optional-pause feature on the shop's plan. Shops without it may only send 1.

Possible values: 0, 1.

Only accepted as 0 when the product is digital. For a physical product the only accepted value is 1.

Possible values: 0, 1.

The product is archived (entity_archived) or belongs to a bundle (product_in_bundle).

A body field fails validation. slug has characters other than letters, digits, dashes and underscores, is over 80 characters, or is used by another product of the shop; gifting_enabled or pre_order_end_at is sent for a digital product; pre_order_end_at is not Y-m-d, is before today, or is set while an active plan has a trial ('One of your plans has a trial enabled. Remove the trial from your plan or pre-order end date first.'); pause_enabled is not 1 and the shop plan lacks optional pause ('Pause is not available on your current plan.'); collect_shipping_address is not 1 on a physical product; tax_product_code is sent by a shop outside the US; inventory_item_id, funnel_id, change_product_collection_id, tags.delete[].id, images.update[].id or images.delete[].id does not belong to the shop or product; tags.create values repeat or are over 255 characters; or images.create has more than 5 entries or an entry without a valid url.

The product is archived (entity_archived), belongs to a bundle (product_in_bundle), has no name or slug (missing_required_fields), has no active plans (no_active_children), or is a physical product with an active plan that has no shipment schedule (missing_shippings).