Introduction

The Swell Backend API is organized around REST principles. It uses predictable resource-oriented URLs, standard HTTP verbs, and response codes. It also accepts and returns JSON-encoded request and response bodies.

Base URL

https://api.swell.store

💡

Official libraries for the Swell API are available for Node and PHP.

Setup

Swell offers both client-side and server-side APIs. This documentation covers topics related to the server-side Backend API.

💡

Use Swell.js for client-side and headless ecommerce.

Attributes

Authentication

Before using the API, you will need to create a Swell account.

Your account provides access to your store ID and API key which are necessary for API access. To get your API keys, navigate to the Developer section in the dashboard's left-hand nav and select API keys.

Your store ID is located at the top of the API keys page.
Click on the eye icon to reveal a Secret key in order to copy it.

💡

You can add or revoke secret keys if the security of any key is compromised.

API authentication differs depending on which library is being used when accessing the API. Refer to the authentication example below when using any of the official API libraries.

👉

While the HTTP protocol is supported, official libraries use a custom wire protocol that improves performance and caching. When using these libraries, your server must be able to connect to the API on port 8443. If you have trouble connecting, have a system administrator check your firewall settings.

Attributes

Authentication example

$ curl https://client_id:client_key@api.swell.store/products

Errors

Swell uses standard HTTP status codes to indicate the success or failure of an API request. A code in the range of 2xx indicates success, a code in the range of 4xx indicates there was a problem with the arguments provided (e.g., a required field was missing), and a code in the range of 5xx indicates an error occurred with Swell's servers.

Validation errors

A validation error object is returned when a request could not be fulfilled due to one or more invalid values.

Attributes

Fields

codestring

A distinct code indicating the cause of the error.

messagestring

A human-readable description of the error.

paramsobject

Object containing parameter values related to the error.

Response

{
  "errors": {
    "name": {
      "code": "REQUIRED",
      "message": "Required"
    },
    "email": {
      "code": "FORMAT_EMAIL",
      "message": "Must be a valid email address"
    }
  }
}

Handling errors

Swell API libraries return a validation error object in case of an invalid PUT, POST, or DELETE request, and throw in any other error case.

Querying

There are several parameters you can use to effect the outcome of a query.

Query parameters

Query parameter reference for querying with Swell's Backend API.

Fields

whereobject

An object containing criteria to filter results by.

sortstring

A string expression used to sort results.

limitint

A number indicating the max number of results to return up to 1000.

pageint

A number indicating which page of results to return.

searchstring

A string to search and filter results by.

expandstring

A string or array of fields to expand in the result.

includeobject

An object with additional queries to include as fields in the result.

Filtering

Use the where parameter to filter results by their values. Swell offers native support for most MongoDB Query Operators including comparison operators like $gt and $lt—logical operators like $and and $or—and many others. You can combine many fields in one query.

Example query using where

$ curl https://api.swell.store/products?where[date_created][$gte]=2018-01-01T00:00:00Z&where[stock_level][$gt]=0&where[active]=true
  -u store-id:secret-key

Sorting

Use the sort parameter to sort results. The format consists of <field> <direction>. Direction is recognized as a case-insensitive word like ascending and descending, or as abbreviated asc and desc.

You can combine multiple sort fields in a string or array, with the first taking precedence in order.

Example query using sort

$ curl https://api.swell.store/products?sort=name+asc
  -u store-id:secret-key

Limiting

Use the limit parameter to determine how many records should be returned in a result, up to 1000. Defaults to 15. Optionally use in combination with page to perform pagination.

Example query using limit

$ curl https://api.swell.store/products?limit=100
  -u store-id:secret-key

Pagination

Use the page parameter to determine which page of results to return, relative to the default or specified limit. Defaults to 1.

Example query using page

$ curl https://api.swell.store/products?page=2
  -u store-id:secret-key

Searching

Use the search parameter to perform a text search across all text fields in a given collection. This is a basic implementation that uses a combination of regular expressions, meaning it will match exact words only. For example, a search for "blue shirts" will match records containing both the words "blue" and "shirts". Searching is not case-sensitive.

👉

When building product search for a complex store, we recommend Algolia.

Example query using search

$ curl https://api.swell.store/products?search=blue+shirts
  -u store-id:secret-key

Expanding

Expanding allows you to include related records as defined by link or collection fields. For example, in the cart model, items are linked to a product with the product field which means they aren't automatically included in the result when retrieving a cart. Since the item product is nested in a list of objects, you would use dot-notation to specify the path to the expandable field.

When the expandable field refers to many records, you may want to specify a limit to include more than the default limit, which is 5. To do that for example, use the format variants:50 with the field name and limit separated by :.

When retrieving a list of results, expand will be performed on all records in the result set.

Example query using expand

$ curl https://api.swell.store/carts/5407e0929fe97f9d4c712a5e?expand=items.product,items.variant
  -u store-id:secret-key

Response

{
  "id": "5407e0929fe97f9d4c712a5e",
  "items": [
    {
      "id": "5407e0929fe97f9d4c712a5f",
      "product_id": "5407e0929fe97f9d4c712a5g",
      "product": {
        "name": "Example product",
        ...
      }
    },
    {...}
  ],
  ...
}

Including

Use the include parameter to include results in a query that may or may not be related to the records being retrieved. For example, when you know there's a need to retrieve two similar records at a time in order to reduce the number of API calls a page would need.

Use include.params to specify relative values to the records returned by the main query. The actual field values will be substituted by the API. Use include.data to specify literal values for filtering the included result.

Example query using `include`

$ curl https://api.swell.store/orders/5407e0929fe97f9d4c712a5f?include[fulfilled_giftcards][url]=/giftcards&include[fulfilled_giftcards][params][order_id]=id&include[fulfilled_giftcards][data][balance][$gt]=0
  -u store-id:secret-key

Response

{
  "id": "5407e0929fe97f9d4c712a5f",
  "fulfilled_giftcards": [
    {
      "id": "5407e0929fe97f9d4c712a5g",
      "balance": 25
    },
    {...}
  ],
  ...
}

Aggregation

Swell offers native support for the MongoDB Aggregation Pipeline; a framework for data aggregation allowing you to summarize data for reporting and other purposes.

Use the aggregate parameter to construct a pipeline according to this Mongo reference.

Example aggregation query

$ curl https://api.swell.store/orders?aggregate[0][$match][$and][0][date_created][$gte]=2018-01-01T00:00:00Z&aggregate[0][$match][$and][1][date_created][$lte]=2019-01-01T00:00:00Z&aggregate[1][$group][count][$sum]=1&aggregate[1][$group][sub_total][$sum]=sub_total&aggregate[1][$group][avg_total][$avg]=sub_total&aggregate[1][$group][day][$dayOfMonth]=date_created&aggregate[1][$group][month][$month]=date_created&aggregate[1][$group][year][$year]=date_created \
  -u store-id:secret-key

Webhooks

Use webhooks to get notified about events that happen in your Swell account. Configuring a webhook involves setting up your own application to receive incoming HTTP calls that contain data describing the event.

To configure a webhook, visit your Swell dashboard and go to Settings > Webhooks. Specify the URL to your webhook handler and one or more events to receive.

The webhook model

Swell is an event-based architecture that allows you to configure webhooks on a variety of events that occur within each of our base data models. These events are easily referenced when creating webhooks from within the Swell dashboard under Developer > Webhooks. All configured webhooks are also available at /:webhooks.

💡

To view webhooks that have fired within your store, see the /events:webhooks endpoint.

Fields

idobjectIdauto

The unique identifier for the webhook.

aliasstring

Alias used to refer to the webhook configuration.

urlstringrequired

URL endpoint for the webhook.

eventsarray of stringrequired

Array of trigger events for the webhook.

enabledboolean

Determines whether the webhook is enabled. Defaults to false.

auto_disabledbooleanauto

Indicates whether the webhook was automatically disabled. This occurs seven days after the first failed attempt and no subsequent successes.

retry_disabled_eventsboolean

Determines whether the webhook retries disabled events.

attempts_failedint

Displays the number failed webhook attempts.

date_first_faileddateauto

The date the webhook's first failed attempt.

date_last_warneddateauto

The date of the last warning for a failed attempt.

date_final_attemptdate

The final attempt for a webhook after continuous failed attempts. Webhooks are disabled 7 days after the first failed attempt.

scheduleobject

Schedule for specifying when a webhook is to be fired.

date_scheduleddate

Date for which the webhook is scheduled to fire.

The webhook model

{
  "url": "http://localhost:5000",
  "enabled": false,
  "alias": "webhook",
  "description": null,
  "events": [
    "order.created",
    "order.submitted",
    "order.updated"
  ],
  "api": "com",
  "date_final_attempt": null,
  "date_scheduled": null,
  "date_created": "2021-09-27T16:30:11.837Z",
  "date_updated": "2021-10-28T16:04:21.648Z",
  "id": "6151f193ae97e82ccbf6f0a7"
}

Create a webhook

When setting up webhooks for custom models, you will need to create them via the API referencing the events listed on the custom model. For webhooks that utilize Swell's standard models, we recommend configuration through the Swell dashboard under Developer tools > Webhooks—each standard model's events are easily referenced within the UI.

Arguments

urlstringrequired

URL endpoint for the webhook.

eventsarray of stringrequired

Array of trigger events for the webhook.

POSTwebhooks

$ curl https://api.swell.store/products:variants \
  -u store-id:secret-key \
  -d url=http://localhost:5000 \
  -d events=order.created, order.submitted \

The webhook model

{
  "url": "http://localhost:5000",
  "enabled": false,
  "alias": "webhook",
  "description": null,
  "events": [
    "order.created",
    "order.submitted",
    "order.updated"
  ],
  "api": "com",
  "date_final_attempt": null,
  "date_scheduled": null,
  "date_created": "2021-09-27T16:30:11.837Z",
  "date_updated": "2021-10-28T16:04:21.648Z",
  "id": "6151f193ae97e82ccbf6f0a7"
}

Retrieve a webhook

Retrieve an existing webhook using the id that was returned during creation.

Arguments

idobjectIdauto

The unique identifier for the webhook.

GETwebhooks/id

$ curl https://api.swell.store/webhooks/{id} \
  -u store-id:secret-key

The webhook model

{
  "url": "http://localhost:5000",
  "enabled": false,
  "alias": "webhook",
  "description": null,
  "events": [
    "order.created",
    "order.submitted",
    "order.updated"
  ],
  "api": "com",
  "date_final_attempt": null,
  "date_scheduled": null,
  "date_created": "2021-09-27T16:30:11.837Z",
  "date_updated": "2021-10-28T16:04:21.648Z",
  "id": "6151f193ae97e82ccbf6f0a7"
}

Update a webhook

Update a webhook.

Arguments

idobjectIdrequired

The unique identifier for the webhook.

aliasstring

Alias used to refer to the webhook configuration.

urlstring

URL endpoint for the webhook.

eventsstring

Array of trigger events for the webhook.

enabledboolean

Determines whether the webhook is enabled. Defaults to false.

retry_disabled_eventsboolean

Determines whether the webhook retries disabled events.

scheduleobject

Schedule for specifying when a webhook is to be fired.

date_scheduleddate

Date for which the webhook is scheduled to fire.

Update

$ curl https://api.swell.store/webhooks/{id} \
  -u store-id:secret-key \
  -d enabled=true \
  -d date_scheduled=2022-04-20T16:20:69.000Z \
  -X PUT

The webhook model

{
  "url": "http://localhost:5000",
  "enabled": false,
  "alias": "webhook",
  "description": null,
  "events": [
    "order.created",
    "order.submitted",
    "order.updated"
  ],
  "api": "com",
  "date_final_attempt": null,
  "date_scheduled": null,
  "date_created": "2021-09-27T16:30:11.837Z",
  "date_updated": "2021-10-28T16:04:21.648Z",
  "id": "6151f193ae97e82ccbf6f0a7"
}

List all webhooks

Return a list of webhooks.

Arguments

expandstring

Expand link fields and child collections by using the expand argument.

For example, expand=account would return a related customer account if one exists.

When the field represents a collection, you can specify the query limit.

For example, expand=variants:10 would return up to 10 records of the variants collection.

See expanding for more details.

fieldsstring

Returns only the specified fields in the result.

For example fields=name,slug would return only the fields name and slug in the response.

Supports nested object and array fields using dot-notation.

For example, items.product_id. The product id is always returned.

includeobject

Include one or more arbitrary queries in the response which are potentially related to the main query.

See including for more details.

limitint

Limit the number of records returned, ranging between 1 and 1000. Defaults to 15.

pageint

The page number of results to return given the specified or default limit.

searchstring

A text search is performed using the search argument. Searchable fields are defined by the model.

For example, search=red would return records containing the word "red" anywhere in the defined text fields.

See searching for more details.

sortstring

Expression to sort results by using a format similar to a SQL sort statement.

For example, sort=name asc would return records sorted by name ascending.

See sorting for more details.

whereobject

An object with criteria to filter the result.

For example, active=true would return records containing a field active with the value true.

It's also possible to use query operators, for example, $eq, $ne, $gt, and more.

See querying for more details.

GETwebhooks

$ curl https://api.swell.store/webhooks?where[active]=true&limit=25&page=1 \
  -u store-id:secret-key \
  -G

The webhook model

{
  "url": "http://localhost:5000",
  "enabled": false,
  "alias": "webhook",
  "description": null,
  "events": [
    "order.created",
    "order.submitted",
    "order.updated"
  ],
  "api": "com",
  "date_final_attempt": null,
  "date_scheduled": null,
  "date_created": "2021-09-27T16:30:11.837Z",
  "date_updated": "2021-10-28T16:04:21.648Z",
  "id": "6151f193ae97e82ccbf6f0a7"
}

Delete a webhook

Delete a webhook.

Arguments

idobjectIdrequired

The id of the webhook to delete.

DELETEwebhooks/:id

$ curl https://api.swell.store/webhooks/662ba123becf7601325cefa3 \
  -u store-id:secret-key \
  -X DELETE

The webhook model

{
  "url": "http://localhost:5000",
  "enabled": false,
  "alias": "webhook",
  "description": null,
  "events": [
    "order.created",
    "order.submitted",
    "order.updated"
  ],
  "api": "com",
  "date_final_attempt": null,
  "date_scheduled": null,
  "date_created": "2021-09-27T16:30:11.837Z",
  "date_updated": "2021-10-28T16:04:21.648Z",
  "id": "6151f193ae97e82ccbf6f0a7"
}

Using HTTPS

You may use an HTTPS URL for your webhook endpoint. In that case, Swell will validate your SSL certificate before sending event data. Your server must be correctly configured to support HTTPS.

Receiving webhooks

Webhook event data is sent as JSON in a POST body. The payload represents a single event with attributes based on the event type. Events may contain additional data attributes that are useful in processing the event.

Your webhook might need to fetch the associated record using data.id before performing a relevant action.

Response

{
  "id": "58991ed385c95b9e2e0aa433",
  "date_created": "2019-02-07T01:11:47.219Z",
  "model": "subscriptions",
  "type": "subscription.paid",
  "data": {
    "id": "58991ed285c95b9e2e0aa42c",
    "payment_id": "5ca3806f0e41a74b7138d085"
  }
}

Responding to webhooks

Your endpoint must respond to successful requests with a 2xx HTTP status code. All other information returned by your script will be ignored. Response codes outside this range will indicate that you were not able to receive the webhook event.

If a webhook is not acknowledged successfully, Swell will continue trying to send it once every hour for up to two days. After this time, we'll send an email alert and continue attempting to deliver the webhook every hour. If your endpoint does not respond after seven days, you will be notified finally and the webhook will be disabled until further action is taken.

Localization

Content localization is supported by providing alternative values for each configured locale. Any string or array of strings can be set in multiple locales with the $locale parameter when creating or updating objects.

Locales can be specified with or without a country code (e.g., en and en-US).

Set locale values

Use the format $locale: { <code>: { <field>: value } } with any PUT or POST request. For nested values, the $locale parameter must be defined on the nearest parent object.

All locale content is optional using this API, even if the setting Require content for this locale is enabled in the Swell dashboard.

Example setting localized content

$ curl https://api.swell.store/products/5cad15bc9b14d1990724663a \
  -u store-id:secret-key \
  -d name="Test product" \
  -d $locale[fr][name]="Test produit" \
  -d $locale[fr][tags]="étiqueter1, étiqueter2" \
  -d $locale[es][name]="Producto de prueba" \
  -d $locale[es][tags]="etiqueta1, etiqueta2" \
  -X PUT

Retrieve localized content

Use the query parameter $locale: <code>, or alternatively an HTTP header X-Locale: <code> with any GET request. All fields with localized values will be returned according to the locale code and fallback settings.

Example retrieving localized content

$ curl https://api.swell.store/products?$locale=es \
  -u store-id:secret-key

Response

{
  "count": 36,
  "results": [
    {
      "id": "5cad15bc9b14d1990724663a",
      "name": "Test produit",
      "tags": ["étiqueter1", "étiqueter2"],
      ...
    }
  ],
  "page": 1,
  ...
}

Retrieve locale values

To retrieve records with $locale values in order to review localized content or build custom localization interfaces, pass an array of locale codes using the parameter $locale: [<code>, ...] with any GET request. All objects with $locale values will be returned matching the specific locale codes requested.

Example retrieving locale values

$ curl https://api.swell.store/products?$locale=en,fr,es \
  -u store-id:secret-key

Response

{
  "count": 36,
  "results": [
    {
      "id": "5cad15bc9b14d1990724663a",
      "name": "Test product",
      "$locale": {
        "en": {
          "name": "Test product",
          "tags": ["tag1", "tag2"]
        },
        "fr": {
          "name": "Test produit",
          "tags": ["étiqueter1", "étiqueter2"]
        },
        "es": {
          "name": "Producto de prueba",
          "tags": ["etiqueta1", "etiqueta2"]
        },
      }
      ...
    }
  ],
  "page": 1,
  ...
}

Pages

The pages model contains data relating to pages within your storefront and the content within them.

👉

We recommend not making changes via the API for the pages model when possible and suggest using the dashboard model editor instead. If you do wish to make changes via the API, see our data model customization guide.

Fields

idobjectId

Unique identifier for the page.

namestringrequired

Human-friendly name of the page.

slugstringrequired

Lowercase, hyphenated identifier typically used in URLs. When creating a product, a slug will be generated automatically from the name. Maximum length of 1,000 characters.

contentstring

HTML formatted page content.

date_createddate

Date and time the page was created.

date_publisheddate

Date and time the page was published.

date_updateddate

Date and time the page was updated.

meta_descriptionstring

Page description used for search engine optimization purposes.

publishedboolean

Indicates whether the page is published. Defaults to false.

redirectstring

URL to specify a page redirect.

The pages model

 {
  "id": "5f5efea5703b7a10d8000007",
  "name": "About Us",
  "slug": "about-us",
  "content": "Welcome to <strong>Strongbad's Awesome Store</strong>. We make awesome things for awesome people.",
  "date_updated": "2021-09-16T01:05:27.003Z",
  "date_published": "2020-09-28T09:08:23.005Z",
  "date_created": "2020-09-28T09:07:17.091Z",
  "meta_description": null,
  "redirect": null,
  "published": true,
  }

Products

Products represent items that can be sold to a customer, either as one-off sales or as subscriptions. For more complex subscription products and when physical items are involved, it's recommended to create a plan.

The product model

Fields

idobjectId

Unique identifier for the product.

namestringrequired

Human-friendly name of the product.

activeboolean

Indicates whether the product is active and available in the storefront.

purchase_optionsobject

Configuration of one or more purchase options for the product. Can be standard for one-time purchases or subscription for a subscription plan. Products can support both purchase options simultaneously.

purchase_options.standardobject

Designates purchase option as a one-time purchase.

purchase_options.subscriptionobject

Designates purchase option for a subscription plan.

subscription.idobjectIdauto

ID of the subscription plan purchase option.

subscription.namestringrequired

Name of the subscription plan purchase option.

subscription.descriptionstring

A long-form description of the purchase option. May contain HTML or other markup languages.

subscription.activeboolean

Indicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the Frontend.

subscription.account_groupsarray of string

Array of account_group names for which the purchase option is available.

subscription.plansarray of plans

Array defining subscription plans and their respective configurations.

attributesobject

An object containing custom attribute key/value pairs.

bundleboolean

Indicates whether the product is a bundle of other products.

bundle_itemsarray of object

List of products sold as a bundle. Applicable only when bundle=true.

categorycategory

Expandable link to the primary category.

category_idobjectId

Primary category, commonly used as a navigation anchor.

categoriescategories

Expandable link to all related product categories.

category_indexobject

Index of categories used for fast lookup operations.

codestring

Unique code to identify the gift card product.

costcurrency

Cost of goods (COGS) used to calculate gross margins.

cross_sellsarray of object

List of products to display as cross-sells on a shopping cart page.

currencystring

Three-letter ISO currency code in uppercase. Defaults to your store's base currency.

customizableboolean

Indicates whether the product has custom options enabled.

date_createddateauto

Date and time the product was created.

date_updateddateauto

Date and time the product was last updated.

deliveryenumauto

Method of fulfillment automatically assigned based on type:

shipment means the product will be physically shipped to a customer.
subscription means the product will be fulfilled as a subscription when an order is placed. giftcard delivery means the product will be fulfilled as a gift card when an order is placed.
null means the product will not be fulfilled by one of the above methods.

Note: A bundle has its child products fulfilled individually; each product in the bundle must have its own fulfillment method.

descriptionstring

A long-form description of the product. May contain HTML or other markup languages.

discontinuedboolean

Indicates whether the product has been discontinued.

imagesarray of object

List of images depicting the bundle.

meta_titlestring

Page title used to override product name in storefronts.

meta_keywordsstring

Page keywords used for search engine optimization purposes.

meta_descriptionstring

Page description used for search engine optimization purposes.

optionsarray of object

Options that allow for variations of the base product. If the option is part of a variant or required=true, an option value must be set for the product to be added to a cart.

idobjectIdauto

Unique identifier for the object.

namestringrequired

Human-friendly name of the option.

input_hintstring

Some brief hint text to help the user understand this option.

input_typeenum

Type of user input to display for this option in a storefront. Can be text, textarea, select, multi_select, file, or multi_file. select is ideal for dropdown or radio selectors, and multi_select is ideal for checkboxes. A maximum of 10 files can be uploaded by the user, and there are no restrictions on file type.

parent_idobjectId

Specifies another option ID that affects visibility of this option. The option will only appear when one of the parent_value_ids is selected.

parent_value_idsarray of child_scalar

IDs of parent option values that will make the option appear if selected.

pricecurrency

Extra price for the option, added to the product's price/sale_price. If the option is part of a variant, the variant's price/sale_price will override this value.

requiredboolean

Indicates whether the option requires a value when the product is added to a cart.

subscriptionboolean

Indicates whether the option specifies the billing interval of a subscription plan.

valuesarray of object

List of possible values for this option.

attribute_idstring

Unique identifier for the attribute.

descriptionstring

Description for the product options.

activeboolean

Indicates the options are active.

input_multiboolean

Indicates there are multiple selections for options.

variantboolean

Indicates the option is a variant.

pricecurrency

List price used when sale=false or sale_price is not defined.

pricesarray of price

Price rules determined by cart quantity or customer account group. Overrides price and sale_price when conditions match.

quantity_minint

Minimum quantity of the product that can be sold at once.

quantity_incint

Specifies a quantify multiple the product must be sold in.

related_product_idsarray of child_scalar

Array of related product IDs.

saleboolean

Indicates whether the product is on sale. If true, the sale_price will be used by default when the product is added to a cart.

sale_pricecurrency

Sale price used to override list price when sale=true.

shipment_dimensionsobjectrequired

Product dimensions when packed for shipping. Typically used by third-party carriers in box packing algorithms to optimize shipping costs.

shipment_locationstring

ID of location from /settings/shipping/locations. If specified, shipping is calculated from this location. Otherwise, the store's default location will be used.

shipment_package_quantityfloat

If specified, shipping is calculated using this as the maximum number of items per package. Otherwise, Swell assumes any quantity fits into a single package.

shipment_pricesarray of object

Product shipping price rules to override default shipping rules.

shipment_weightfloat

If specified, shipping is calculated using this weight. Otherwise, Swell assumes 1 lb/oz/kg—depending on the store's default weight unit.

subscription_intervalenum

The default billing interval when this product is used as a subscription plan. Can be monthly, yearly, weekly, or daily.

subscription_interval_countint

Multiplier when combined with subscription_interval. For example, to make a subscription bill every two weeks, set subscription_interval=weekly and subscription_interval_count=2.

subscription_trial_daysint

Number of days offered as a free trial before the customer is billed. If a subscription is canceled by the last day of the trial period, an invoice won't be issued.

skustringrequired

Stock keeping unit (SKU) used to track inventory in a warehouse.

slugstringrequired

Lowercase, hyphenated identifier typically used in URLs. When creating a product, a slug will be generated automatically from the name. Maximum length of 1,000 characters.

stockarray of Stock

Expandable list of stock adjustments for the product.

stock_backorderboolean

Indicates whether the product can be backordered if out of stock.

stock_levelint

Quantity of the product currently in stock (including all variants), based on the sum of the stock entries.

stock_preorderboolean

Indicates whether the product can be purchased as a preorder.

stock_purchasableboolean

Indicates whether the product's stock is purchasable.

stock_statusenumauto

String indicating the product's stock status for the purpose of ordering. When stock_purchasable=true, an order can be placed for this product regardless of current stock status. Otherwise an order submission will be blocked unless stock status is available, preorder, or backorder.

stock_trackingboolean

Indicates whether the product has stock tracking enabled.

tagsarray of child_scalar

Array of searchable tags to aid in search discoverability.

tax_classstring

Indicates the tax class for the product.

tax_codestring

Product tax code for tracking with Avalara, TaxJar, etc.

typestring

Implies the ordering and fulfillment options available for the product. Can be standard, subscription, bundle, or giftcard. A standard product is a physical item that will be shipped to a customer.

up_sellsarray of object

List of products to display as up-sells on a product detail page.

variableboolean

Indicates whether the product has variant generation enabled.

variantsarray of Variants

Expandable list of variants representing unique variations of the product. Each variant is a combination of one or more options. For example, Size and Color.

virtualboolean

Indicates whether the product is virtual.

The product model

{
  "name": "Iron dagger",
  "sku": "00090616",
  "active": true,
  "purchase_options": {
    "standard": {
      "active": true,
      "price": 10,
      "sale_price": null,
      "sale": false,
      "prices": []
    },
    "subscription": {
      "active": true,
      "plans": [
        {
          "name": "Monthly",
          "description": "1 dagger/month",
          "price": 9,
          "billing_schedule": {
            "interval": "monthly",
            "interval_count": 1,
            "limit": null,
            "trial_days": 14
          },
          "id": "627c6f180d375a001296b593",
          "active": true
        }
      ]
    }
  },
  "variable": true,
  "description": "<h3>Damage: 7</h3><h3>Weight: 8</h3><h3>Health: 98</h3><h3>Speed: 1.4</h3><h3>Reach: 0.6</h3>",
  "tags": [],
  "meta_title": null,
  "meta_description": null,
  "slug": "iron-dagger",
  "attributes": {
    "blade": "",
    "dagger": "",
    "type": [
      "Fine",
      "Rusty"
    ]
  },
  "delivery": "shipment",
  "bundle": null,
  "price": 10,
  "stock_tracking": false,
  "options": [
    {
      "id": "627c6e36e80393798c171670",
      "values": [
        {
          "id": "627c6f18e80393798c171673",
          "name": "Fine",
          "price": null,
          "shipment_weight": null,
          "description": "A better-than-usual iron dagger"
        },
        {
          "id": "627c6f18e80393798c171674",
          "name": "Rusty",
          "price": 0,
          "shipment_weight": null,
          "description": "This dagger's seen better days"
        }
      ],
      "name": "Type",
      "active": true,
      "input_type": "select",
      "variant": true,
      "description": null,
      "required": true,
      "attribute_id": "type"
    }
  ],
  "currency": "USD",
  "sale": false,
  "sale_price": null,
  "prices": [],
  "type": "standard",
  "tax_class": "standard",
  "date_created": "2022-05-12T02:21:12.534Z",
  "stock_status": null,
  "date_updated": "2022-05-12T02:37:45.666Z",
  "category_index": {
    "sort": {
      "627c6db5632818001272f8ed": 0,
      "627c6dc30d375a001296a8b7": 0
    },
    "id": [
      "627c6db5632818001272f8ed",
      "627c6dc30d375a001296a8b7"
    ]
  },
  "cross_sells": [],
  "up_sells": [
    {
      "id": "627c7225e80393798c17167b",
      "product_id": "627c715e632818001274ebd8"
    }
  ],
  "id": "627c6f180d375a001296b580"

Create a product

Create a new product.

Arguments

namestringrequired

Human-friendly name of the product.

attributesobject

An object containing custom attribute key/value pairs. See attributes for more details.

pricecurrency

List price used when sale=false or sale_price is not defined.

slugstring

Lowercase, hyphenated identifier typically used in URLs. When creating a product, a slug will be generated automatically from the name. Maximum length of 1,000 characters.

purchase_optionsobject

purchase_options.standardobject

Designates purchase option as a one-time purchase.

purchase_options.subscriptionobject

Designates purchase option as a subscription plan.

subscription.idobjectId

ID of the subscription plan purchase option.

subscription.namestringrequired

Name of the subscription plan purchase option.

subscription.descriptionstring

A long-form description of the purchase option. May contain HTML or other markup languages.

subscription.activeboolean

Indicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the Frontend.

subscription.account_groupsarray of string

Array of account_group names for which the purchase option is available.

subscription.plansarray of object

Array defining subscription plans and their respective configurations.

deliveryenum

Method of fulfillment automatically assigned based on type:

shipment means the product will be physically shipped to a customer.
subscription means the product will be fulfilled as a subscription when an order is placed. giftcard delivery means the product will be fulfilled as a gift card when an order is placed.
null means the product will not be fulfilled by one of the above methods.

Note: A bundle has its child products fulfilled individually; each product in the bundle must have its own fulfillment method.

activeboolean

Set true to make the product visible to customers in a storefront, otherwise it will be hidden.

bundleboolean

Indicates whether the product is a bundle of other products.

bundle_itemsarray of object

List of products sold as a bundle. Applicable only when bundle=true.

category_idobjectId

Primary category, commonly used as a navigation anchor.

costcurrency

Cost of goods (COGS) that is used to calculate gross margins.

cross_sellsarray of object

List of products to display as cross-sells on a shopping cart page.

customizableboolean

Set true to enable custom options for this product in the admin panel.

descriptionstring

A long form description of the product. May have HTML or other markup.

imagesarray of object

List of images depicting the bundle.

meta_descriptionstring

Page description used for search engine optimization purposes.

meta_keywordsstring

Page keywords used for search engine optimization purposes.

meta_titlestring

Page title used to override product name in storefronts.

pricesarray of object

Set price rules to use when conditions match the customer's account group or product quantity in a cart.

quantity_incint

Specifies a quantified multiple the product must be sold in.

quantity_minint

Minimum quantity of the product that can be sold at once.

saleboolean

Set true to mark the product "on sale" and to use sale_price when the product is added to a cart.

sale_pricecurrency

Sale price used to override list price when sale=true.

shipment_dimensionsobject

Product dimensions when packed for shipping. Typically used by 3rd party carriers in box packing algorithms to optimize shipping costs.

shipment_locationstring

ID of location from /settings/shipping/locations. If specified, shipping is calculated from this origin. Otherwise, the store's default location will be used.

shipment_pricesarray of object

Product shipping price rules to override default shipping rules.

shipment_package_quantityfloat

If specified, shipping is calculated using this as the maximum number of items per package. Otherwise, Swell assumes any quantity fits into a single package.

shipment_weightfloat

If specified, shipping is calculated using this weight. Otherwise, Swell assumes 1 lb/oz/kg — depending on store's default weight unit.

skustring

Stock keeping unit (SKU) used to track inventory in a warehouse.

stock_trackingboolean

Set true to enable stock tracking this product.

subscription_intervalenum

The default billing interval when this product is used as a subscription plan. Can be monthly, yearly, weekly, or daily.

subscription_interval_countint

Multiplier when combined with subscription_interval. For example, to make a subscription bill every 2 weeks, set subscription_interval=weekly and subscription_interval_count=2.

subscription_trial_daysint

Number of days offered as a free trial before the customer is billed. If a subscription is canceled by the last day of the trial period, an invoice won't be issued.

up_sellsarray of object

List of products to display as up-sells on a product detail page.

variableboolean

Set true to generate variants for this product in the admin panel.

categorycategory

Expandable link to the primary category.

categoriescategories

Expandable link to all related product categories.

category_indexobject

Index of categories used for fast lookup operations.

stockarray of Stock

Expandable list of stock adjustments for the product.

stock_levelint

Quantity of the product currently in stock (including all variants), based on the sum of the stock entries.

stock_statusenumauto

String indicating the product's stock status for the purpose of ordering. When stock_purchasable=true, an order can be placed for this product regardless of current stock status, otherwise an order submission will be blocked unless stock status is available, preorder ,or backorder.

currencystring

Three-letter ISO currency code in uppercase. Defaults to your store's base currency.

POST/products

$ curl https://api.swell.store/products \
  -u store-id:secret-key \
  -d name="T-Shirt" \
  -d price=99 \
  -d active=true \
  -d options[0][name]=Size \
  -d options[0][values][0][name]=Small \
  -d options[0][values][1][name]=Large

Response

{
  "id": "5ca24abb9c077817e5fe2b36",
  "active": true,
  "attributes": {},
  "currency": "USD",
  "date_created": "2019-04-01T00:00:00.000Z",
  "delivery": "shipment",
  "name": "T-Shirt",
  "options": [
    {
      "id": "5ca24ab32599d4179c24a624",
      "name": "Size",
      "variant": true,
      "required": true,
      "values": [
        {
          "id": "5ca24ad59c077817e5fe2ba3",
          "name": "Small"
        },
        {
          "id": "5ca24ad59c077817e5fe2ba4",
          "name": "Medium"
        },
        {
          "id": "5ca24ad59c077817e5fe2ba5",
          "name": "Large"
        }
      ]
    }
  ],
  "price": 99.00,
  "slug": "swell-t-shirt",
  "type": "standard"
}

Retrieve a product

Retrieve an existing product using the ID that was returned when created.

Arguments

idobjectIdrequired

The id of the product to retrieve.

expandstring

Expanding link fields and child collections is performed using the expand argument.

For example, expand=account would return a related customer account if one exists.

When the field represents a collection, you can specify the query limit.

For example, expand=variants:10 would return up to 10 records of the variants collection.

See expanding for more details.

fieldsstring

Return only the specified fields in the result. For example fields=name,slug would return only the fields name and slug in the response. Supports nested object and array fields using dot-notation.

For example, items.product_id. The category id is always returned.

includestring

Include one or more arbitrary queries in the response, possibly related to the main query.

See including for more details.

GET/products/:id

$ curl https://api.swell.store/products/5c8fb5e1ed2faf8c79da492a \
  -u store-id:secret-key

Response

{
  "id": "5ca24abb9c077817e5fe2b36",
  "active": true,
  "attributes": {},
  "currency": "USD",
  "date_created": "2019-04-01T00:00:00.000Z",
  "date_updated": "2019-04-02T00:26:23.399Z",
  "delivery": "shipment",
  "description": null,
  "images": [
    {
      "id": "5ca24abb9c077817e5fe2b37",
      "file": {
        "id": "5ca24abb9c077817e5fe2b38",
        "date_uploaded": "2019-04-02T00:26:23.399Z",
        "length": 66764,
        "md5": "99194f53bfdea832553e7fa8ae8fd80f",
        "content_type": "image/png",
        "url": "http://cdn.swell.store/test/5ca24abb9c077817e5fe2b36/99194f53bfdea832553e7fa8ae8fd80f",
        "width": 940,
        "height": 600
      }
    }
  ],
  "meta_description": null,
  "meta_title": null,
  "name": "T-Shirt",
  "options": [
    {
      "id": "5ca24ab32599d4179c24a624",
      "name": "Size",
      "variant": true,
      "required": true,
      "values": [
        {
          "id": "5ca24ad59c077817e5fe2ba3",
          "name": "Small"
        },
        {
          "id": "5ca24ad59c077817e5fe2ba4",
          "name": "Medium"
        },
        {
          "id": "5ca24ad59c077817e5fe2ba5",
          "name": "Large"
        }
      ]
    }
  ],
  "price": 9.99,
  "slug": "swell-t-shirt",
  "stock_level": 0,
  "stock_status": "available",
  "stock_tracking": true,
  "tags": [],
  "type": "standard"
}

Update a product

Updates an existing product using the ID that was returned when created. Updating performs a merge operation. To explicitly override values such as arrays, use the $set operator.

Arguments

idobjectIdrequired

Unique identifier for the product.

activeboolean

Set true to make the product visible to customers in a storefront, otherwise it will be hidden.

attributesobject

An object containing custom attribute key/value pairs. See attributes for more details.

namestring

Human-friendly name of the product.

pricecurrency

List price used when sale=false or sale_price is not defined.

slugstring

Lowercase, hyphenated identifier typically used in URLs. When creating a product, a slug will be generated automatically from the name. Maximum length of 1,000 characters.

purchase_optionsobject

purchase_options.standardobject

Designates purchase option as a one-time purchase.

purchase_options.subscriptionobject

Designates purchase option as a subscription plan.

subscription.idobjectIdauto

ID of the subscription plan purchase option.

subscription.namestringrequired

Name of the subscription plan purchase option.

subscription.descriptionstring

A long-form description of the purchase option. May contain HTML or other markup languages.

subscription.activeboolean

Indicates whether the purchase option is available for customers to purchase. Inactive products will not be returned on the Frontend.

subscription.account_groupsarray of string

Array of account_group names for which the purchase option is available.

subscription.plansarray of plans

Array defining subscription plans and their respective configurations.

bundleboolean

Indicates whether the product is a bundle of other products.

bundle_itemsobject

List of products sold as a bundle. Applicable only when bundle=true.

category_idobjectId

Primary category, commonly used as a navigation anchor.

costcurrency

Cost of goods (COGS) used to calculate gross margins.

cross_sellsobject

List of products to display as cross-sells on a shopping cart page.

customizableboolean

Set true to enable custom options for this product in the admin panel.

descriptionstring

A long form description of the product. May have HTML or other markup.

imagesobject

List of images depicting the bundle.

meta_descriptionstring

Page description used for search engine optimization purposes.

meta_keywordsstring

Page keywords used for search engine optimization purposes.

meta_titlestring

Page title used to override product name in storefronts.

Optionsobject

Options that allow for variations of the base product. If the option is part of a variant or required=true, an option value must be set for the product to be added to a cart.

Options.namestring

Human-friendly name of the option.

Options.input_hintstring

Some brief hint text to help the user understand this option.

Options.input_typestring

Type of user input to display for this option in a storefront. Can be text, textarea, select, multi_select, file or multi_file. select is ideal for dropdown or radio selectors, and multi_select is ideal for checkboxes. A maximum of 10 files can be uploaded by the user, and there are no restrictions on file type.

Options.parent_idobjectId

Specifies another option ID that affects visibility of this option. The option will only appear when one of the parent_value_ids is selected.

Options.parent_value_idsarray of objectId

The ids of parent option values that will make the option appear if selected.

Options.pricecurrency

Extra price for the option, added to the product's price/sale_price. If the option is part of a variant, the variant's price/sale_price will override this value.

Options.subscriptionboolean

Set true to indicate the option's values specify a subscription billing interval. In this case, option values must have a subscription_interval of monthly, yearly, weekly or daily.

Options.valuesobject

List of possible values for this option.

Options.variantboolean

Set true to generate variants including this option.

pricesobject

Set price rules to use when conditions match the customer's account group or product quantity in a cart.

quantity_incint

Specifies a quantity multiple the product must be sold in.

quantity_minint

Minimum quantity of the product that can be sold at once.

saleboolean

Set true to mark the product "on sale" and to use sale_price when the product is added to a cart.

sale_pricecurrency

Sale price used to override list price when sale=true.

shipment_dimensionsobject

Product dimensions when packed for shipping. Typically used by 3rd party carriers in box packing algorithms to optimize shipping costs.

shipment_locationstring

ID of location from /settings/shipping/locations. If specified, shipping is calculated from this origin. Otherwise, the store default location will be used.

shipment_package_quantityfloat

If specified, shipping is calculated using this as the maximum number of items per package. Otherwise, Swell assumes any quantity fits into a single package.

shipment_pricesobject

Product shipping price rules to override default shipping rules.

shipment_weightfloat

If specified, shipping is calculated using this weight. Otherwise, Swell assumes 1 lb/oz/kg — depending on store's default weight unit.

skustring

Stock keeping unit (SKU) used to track inventory in a warehouse.

stock_trackingboolean

Set true to enable stock tracking this product.

subscription_intervalstring

The default billing interval when this product is used as a subscription plan. Can be monthly, yearly, weekly or daily.

subscription_interval_countint

Multiplier when combined with subscription_interval. For example, to make a subscription bill every 2 weeks, set subscription_interval=weekly and subscription_interval_count=2.

subscription_trial_daysint

Number of days offered as a free trial before the customer is billed. If a subscription is canceled by the last day of the trial period, an invoice won't be issued.

tagsarray of string

List of arbitrary tags typically used as metadata to improve search results or associate custom behavior with a product.

typestring

Implies the ordering and fulfillment options available for the product. Can be standard, subscription, bundle, or giftcard. A standard product is a physical item that will be shipped to a customer.

up_sellsobject

List of products to display as up-sells on a product detail page.

variableboolean

Set true to generate variants for this product in the admin panel.

Update a product

$ curl https://api.swell.store/products/5c8fb5e1ed2faf8c79da492a \
  -u store-id:secret-key \
  -d price=9.99 \
  -X PUT

Response

{
  "id": "5ca24abb9c077817e5fe2b36",
  "active": true,
  "attributes": {},
  "currency": "USD",
  "date_created": "2019-04-01T00:00:00.000Z",
  "date_updated": "2019-04-01T00:00:00.000Z",
  "delivery": "shipment",
  "description": null,
  "images": [
    {
      "id": "5ca24abb9c077817e5fe2b37",
      "file": {
        "id": "5ca24abb9c077817e5fe2b38",
        "date_uploaded": "2019-04-02T00:26:23.399Z",
        "length": 66764,
        "md5": "99194f53bfdea832553e7fa8ae8fd80f",
        "content_type": "image/png",
        "url": "http://cdn.swell.store/test/5ca24abb9c077817e5fe2b36/99194f53bfdea832553e7fa8ae8fd80f",
        "width": 940,
        "height": 600
      }
    }
  ],
  "meta_description": null,
  "meta_title": null,
  "name": "T-Shirt",
  "options": [
    {
      "id": "5ca24ab32599d4179c24a624",
      "name": "Size",
      "variant": true,
      "required": true,
      "values": [
        {
          "id": "5ca24ad59c077817e5fe2ba3",
          "name": "Small"
        },
        {
          "id": "5ca24ad59c077817e5fe2ba4",
          "name": "Medium"
        },
        {
          "id": "5ca24ad59c077817e5fe2ba5",
          "name": "Large"
        }
      ]
    }
  ],
  "price": 9.99,
  "slug": "swell-t-shirt",
  "stock_level": 0,
  "stock_status": "available",
  "stock_tracking": true,
  "tags": [],
  "type": "standard"
}

List all products

Return a list of products.

Arguments

expandstring

Expand link fields and child collections by using the expand argument.

For example, expand=account would return a related customer account if one exists.

When the field represents a collection, you can specify the query limit.

For example, expand=variants:10 would return up to 10 records of the variants collection.

See expanding for more details.

fieldsstring

Returns only the specified fields in the result.

For example fields=name,slug would return only the fields name and slug in the response.

Supports nested object and array fields using dot-notation.

For example, items.product_id. The product id is always returned.

includeobject

Include one or more arbitrary queries in the response which are potentially related to the main query.

See including for more details.

limitint

Limit the number of records returned, ranging between 1 and 1000. Defaults to 15.

pageint

The page number of results to return given the specified or default limit.

searchstring

A text search is performed using the search argument. Searchable fields are defined by the model.

For example, search=red would return records containing the word "red" anywhere in the defined text fields.

See searching for more details.

sortstring

Expression to sort results by using a format similar to a SQL sort statement.

For example, sort=name asc would return records sorted by name ascending.

See sorting for more details.

whereobject

An object with criteria to filter the result.

For example, active=true would return records containing a field active with the value true.

It's also possible to use query operators, for example, $eq, $ne, $gt, and more.

See querying for more details.

GET/products

$ curl https://api.swell.store/products?where[active]=true&limit=25&page=1 \
  -u store-id:secret-key \
  -G

Response

{
  "count": 51,
  "results": [
    {
      "id": "5ca24abb9c077817e5fe2b36",
      "active": true,
      "attributes": {},
      "currency": "USD",
      "date_created": "2019-04-01T00:00:00.000Z",
      "date_updated": "2019-04-01T00:00:00.000Z",
      "delivery": "shipment",
      "description": null,
      "images": [],
      "meta_description": null,
      "meta_title": null,
      "name": "T-Shirt",
      "options": [],
      "price": 9.99,
      "slug": "swell-t-shirt",
      "stock_level": 0,
      "stock_status": "available",
      "stock_tracking": true,
      "tags": [],
      "type": "standard"
    },
    {...},
    {...}
  ],
  "page": 1,
  "pages": {
    "1": {
      "start": 1,
      "end": 25
    },
    "2": {
      "start": 26,
      "end": 50
    },
    "2": {
      "start": 51,
      "end": 51
    }
  }
}

Delete a product

Deleting a product that has already been sold will break any links that exist within orders. We recommend only deleting products that have not yet been sold to a customer.

⚠️

When deleting a record that has child collections such as variants and stock, the contents of those collections are also deleted.

Arguments

idobjectIdrequired

The id of the product you wish to delete.

DELETE/products/:id

$ curl https://api.swell.store/products/5c8fb5e1ed2faf8c79da492a \
  -u store-id:secret-key \
  -X DELETE

Response

{
  "id": "5ca24abb9c077817e5fe2b36",
  "active": true,
  "attributes": {},
  "currency": "USD",
  "date_created": "2019-04-01T00:00:00.000Z",
  "date_updated": "2019-04-01T00:00:00.000Z",
  "delivery": "shipment",
  "description": null,
  "images": [],
  "meta_description": null,
  "meta_title": null,
  "name": "T-Shirt",
  "options": [],
  "price": 9.99,
  "slug": "swell-t-shirt",
  "stock_level": 0,
  "stock_status": "available",
  "stock_tracking": true,
  "tags": [],
  "type": "standard"
}

Variants

Product variants represent unique variations of a product that support stock tracking. Each variant is a combination of one or more options, for example, Size or Color. Variants are children of products.

The variant model

Fields

idobjectIdauto

Unique identifier for the variant.

namestringrequired

Human-friendly name of the variant. Defaults to the combined name of all options, for example "Blue, Large" in the case of 2 options; color and size.

parent_idobjectIdrequired

The id of the parent product.

activeboolean

An active variant is visible to customers in a storefront. Otherwise it will be hidden from view.

archivedboolean

A variant is automatically archived when it has been sold in the past and product options are changed in a way that would cause the variant to be removed.

attributesobject

An object containing custom attribute values. Overrides product attributes. See attributes for more details.

codestring

Unique code to identify the gift card variant.

costcurrency

Cost of goods used to calculate gross margins. Overrides parent product cost.

currencystring

Three-letter ISO currency code in uppercase. Defaults to store's base currency.

date_createddateauto

Date and time the variant was created.

date_updateddateauto

Date and time the variant was last updated.

imagesarray of objectrequired

List of images depicting the variant.

option_value_idsarray of child_scalar

List of option value IDs that constitute the variant.

parentparent

Expandable link to the parent product.

pricecurrency

List price used by default when sale=false or sale_price is not defined. Overrides parent product price.

pricesarray of objectrequired

Price rules to override price and sale_price when conditions match quantity or account group in a cart. Overrides parent product prices.

purchase_optionsobject

Purchase options available for the product variant.

saleboolean

Indicates the variant is on sale andsale_price is used by default when the product is added to a cart. Overrides parent product sale.

sale_pricecurrencyrequired

Sale price used by default when sale=true, overriding price. Overrides parent product sale_price.

shipment_weightfloat

If specified, shipping is calculated based on this shipping weight. Otherwise, it will assume 1 lb/oz/kg depending on your default weight unit. Overrides parent product shipment_weight.

skustring

Stock keeping unit (SKU) used to track inventory in a warehouse.

stockstock

Expandable list of stock adjustments for the variant.

stock_levelint

Current in-stock quantity of the variant, based on the sum of stock entries.

subscription_intervalenum

The default billing interval when this product is used as a subscription plan. Can be monthly, yearly, weekly or daily.

subscription_interval_countint

Multiplier when combined with subscription_interval. For example, to make a subscription bill every 2 weeks, set subscription_interval=weekly and subscription_interval_count=2.

subscription_trial_daysint

Number of days offered as a free trial before the customer is billed. If a subscription is canceled by the last day of the trial period, an invoice won't be issued.

The product variant model

{
  "id": "60f199509111e70000000067",
  "name": "Medium",
  "parent_id": "60f199509111e70000000069",
  "active": true,
  "archived": false,
  "attributes": {
    "example": true
  },
  "currency": "USD",
  "date_created": "2021-07-16T14:36:00.333Z",
  "date_updated": "2021-07-16T14:36:00.333Z",
  "images": [
    {
      "id": "5ca24abb9c077817e5fe2b37",
      "caption": "Just a variant",
      "file": {
        "id": "5ca24abb9c077817e5fe2b38",
        "length": 66764,
        "md5": "99194f53bfdea832553e7fa8ae8fd80f",
        "content_type": "image/png",
        "url": "http://cdn.swell.store/test/5ca24abb9c077817e5fe2b36/99194f53bfdea832553e7fa8ae8fd80f",
        "width": 940,
        "height": 600
      }
    }
  ],
  "option_value_ids": [
    "59764b54e68ba2330390319a"
  ],
  "price": 18.99,
  "sale": false,
  "sale_price": null,
  "sku": "EX2001",
  "stock_level": 6
}

Create a variant

Create a new variant. Normally, variants are automatically created when product options are set.

Arguments

namestringrequired

Human-friendly name of the variant. Defaults to the combined name of all options, for example, "Blue, Large" in the case of 2 options; color and size.

parent_idobjectIdrequired

The id of the parent product.

attributesobject

An object containing custom attribute values. Overrides product attributes. See attributes for more details.

option_value_idsarray of objectId

List of option value IDs that constitute the variant.

pricecurrency

List price used by default when sale=false or sale_price is not defined. Overrides product price.

POST/product:variants

$ curl https://api.swell.store/products:variants \
  -u store-id:secret-key \
  -d parent_id=5ca24abb9c077817e5fe2b36
  -d name="Blue, Small"

Response

{
  "id": "5c8fb5e1ed2faf8c79da492a",
  "parent_id": "5ca24abb9c077817e5fe2b36",
  "name": "Blue, Small",
  "active": true,
  "currency": "USD",
  "date_created": "2019-04-01T00:00:00.000Z"
}

Retrieve a variant

Retrieve an existing variant using the id that was returned when created.

Arguments

idobjectIdrequired

The id of the variant to retrieve.

expandstring

Expanding link fields and child collections is performed using the expand argument.

For example, expand=account would return a related customer account if one exists.

When the field represents a collection, you can specify the query limit.

For example, expand=variants:10 would return up to 10 records of the variants collection.

See expanding for more details.

fieldsstring

Return only the specified fields in the result.

For example fields=name,slug would return only the fields name and slug in the response.

Supports nested object and array fields using dot-notation

For example items.product_id. The variant id is always returned.

includestring

Include one or more arbitrary queries in the response, possibly related to the main query.

See including for more details.

GET/product:variants/:id

$ curl https://api.swell.store/products:variants/5c8fb5e1ed2faf8c79da492a \
  -u store-id:secret-key

Response

{
  "id": "5c8fb5e1ed2faf8c79da492a",
  "parent_id": "5ca24abb9c077817e5fe2b36",
  "name": "Blue, Small",
  "active": true,
  "currency": "USD",
  "date_created": "2019-04-01T00:00:00.000Z"
  "date_updated": "2019-04-01T00:00:00.000Z",
}

Update a variant

Update an existing product using the ID that was returned when created. Updating performs a merge operation. To explicitly override values such as arrays, use the $set operator.

Arguments

idobjectId

Unique identifier for the variant.

parent_idobjectId

The id of the parent product.

activeboolean

An active variant is visible to customers in a storefront, otherwise it will be hidden from view.

attributesobject

An object containing custom attribute values. Overrides product attributes. See attributes for more details.

namestring

Human-friendly name of the variant. Defaults to the combined name of all options, for example, "Blue, Large" in the case of 2 options; color and size.

pricecurrency

List price used by default when sale=false or sale_price is not defined. Overrides product price.

PUT/products:variants/:id

$ curl https://api.swell.store/products:variants/5c8fb5e1ed2faf8c79da492a \
  -u store-id:secret-key \
  -d price=19.98 \
  -X PUT

Response

{
  "id": "5c8fb5e1ed2faf8c79da492a",
  "parent_id": "5ca24abb9c077817e5fe2b36",
  "name": "Blue, Small",
  "active": true,
  "currency": "USD",
  "date_created": "2019-04-01T00:00:00.000Z",
  "date_updated": "2019-04-01T00:00:00.000Z",
  "price": 19.98
}

List all variants

Return a list of product variants.

Arguments

expandstring

Expand link fields and child collections by using the expand argument.

For example, expand=account would return a related customer account if one exists.

When the field represents a collection, you can specify the query limit.

For example, expand=variants:10 would return up to 10 records of the variants collection.

See expanding for more details.

fieldsstring

Returns only the specified fields in the result.

For example fields=name,slug would return only the fields name and slug in the response.

Supports nested object and array fields using dot-notation.

For example, items.product_id. The product id is always returned.

includeobject

Include one or more arbitrary queries in the response which are potentially related to the main query.

See including for more details.

limitint

Limit the number of records returned, ranging between 1 and 1000. Defaults to 15.

pageint

The page number of results to return given the specified or default limit.

searchstring

A text search is performed using the search argument. Searchable fields are defined by the model.

For example, search=red would return records containing the word "red" anywhere in the defined text fields.

See searching for more details.

sortstring

Expression to sort results by using a format similar to a SQL sort statement.

For example, sort=name asc would return records sorted by name ascending.

See sorting for more details.

whereobject

An object with criteria to filter the result.

For example, active=true would return records containing a field active with the value true.

It's also possible to use query operators, for example, $eq, $ne, $gt, and more.

See querying for more details.

GET/products:variants

$ curl https://api.swell.store/products:variants?where[active]=true&limit=25&page=1 \
  -u store-id:secret-key \
  -G

Response

{
  "count":</

Filter

What would you like to search for?

Fields

Response

Fields

Response

Response

Fields

The webhook model

Arguments

The webhook model

Arguments

The webhook model

Arguments

The webhook model

Arguments

The webhook model

Arguments

The webhook model

Response

Response

Response

Fields

The pages model

Fields

The product model

Arguments

Response

Arguments

Response

Arguments

Response

Arguments

Response

Arguments

Response

Fields

The product variant model

Arguments

Response

Arguments

Response

Arguments

Response

Arguments

Response