Backend API

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

Base URL
https://api.swell.store
💡

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

Getting started

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.

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.

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.

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

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.

Receiving a webhook

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 a webhook

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.

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.

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,
  ...
}

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

Whether the product is available for customers to purchase. Inactive products will not be returned in the Frontend API.

attributesobject

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

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.

categoriesCategory

Expandable link to all related product categories.

category_indexobject

Index of categories used for fast lookup operations.

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.

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.

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.

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.

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.

variableboolean

Indicates whether the product has variant generation enabled.

stock_trackingboolean

Indicates whether the product has stock tracking enabled.

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.

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.

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.

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.

The product model
{
  "id": "60f199509111e7000000006a",
  "name": "Example product",
  "active": true,
  "attributes": {
    "material": "Cotton",
    "wash": "Machine",
    "fit": "Runs small",
    "example": true
  },
  "cost": 9,
  "cross_sells": [
    {
      "id": "5cab78ab2045865e3c8a3794",
      "product_id": "5cab78ab2045865e3c8a3795",
      "discount_type": "percent",
      "discount_percent": 10
    }
  ],
  "currency": "USD",
  "customizable": false,
  "date_created": "2021-07-16T14:36:00.367Z",
  "date_updated": "2021-07-16T14:36:00.367Z",
  "delivery": "shipment",
  "description": "A long form description of the product.",
  "images": [
    {
      "id": "5cab78ab2045865e3c8a3794",
      "caption": "This is interesting",
      "file": {
        "id": "5cab78ab2045865e3c8a375",
        "length": 66764,
        "md5": "99194f53bfdea832553e7fa8ae8fd80f",
        "content_type": "image/png",
        "url": "http://cdn.swell.store/test/5ca24abb9c077817e5fe2b36/99194f53bfdea832553e7fa8ae8fd80f",
        "width": 940,
        "height": 600
      }
    }
  ],
  "meta_description": null,
  "meta_keywords": null,
  "meta_title": null,
  "options": [
    {
      "id": "5ca24abb9c077817e5fe2b38",
      "name": "Size",
      "variant": true,
      "values": [
        {
          "id": "5ca24abb9c077817e5fe2b39",
          "name": "Small"
        },
        {
          "id": "5ca24abb9c077817e5fe2b30",
          "name": "Large",
          "price": 2.99
        }
      ]
    }
  ],
  "prices": [
    {
      "price": 10,
      "quantity_min": 5,
      "quantity_max": 15
    },
    {
      "price": 8,
      "quantity_min": 15,
      "account_group": "wholesale"
    }
  ],
  "review_rating": 4.6,
  "sale": false,
  "sale_price": 19.99,
  "shipment_dimensions": {
    "length": 18,
    "width": 12,
    "height": 6,
    "unit": "in"
  },
  "sku": "EX2000",
  "slug": "example-product",
  "stock_level": 13,
  "stock_tracking": true,
  "tags": [
    "example",
    "one",
    "two"
  ],
  "type": "standard",
  "up_sells": [
    {
      "id": "5cab78ab2045865e3c8a3794",
      "product_id": "5cab78ab2045865e3c8a3795"
    }
  ],
  "variable": true
}

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 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.

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 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.

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

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.

parentProduct

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.

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.

purchase_optionsobject

Purchase options available for the product variant.

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": 15,
  "results": [
    {
      "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
    },
    {...},
    {...}
  ],
  "page": 1,
  "pages": {
    "1": {
      "start": 1,
      "end": 15
    }
  }
}

Delete a variant

Delete a variant. Try to avoid deleting variants that have been sold to a customer, as the link to existing orders will be broken.

Arguments

idobjectIdrequired

The id of the variant to delete.

DELETE/products:variants/:id
$ curl https://api.swell.store/products:variants/5c8fb5e1ed2faf8c79da492a \
  -u store-id:secret-key \
  -X DELETE
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
}

Stock

Stock adjustments are used to keep track of inventory changes over time. Each record represents a single change of 1 or more quantities. When adjustments are made, product and variant stock levels are updated automatically. Stock adjustments are children of products.

The stock model

Fields

idobjectId

Unique identifier for the stock adjustment.

parent_idobjectIdrequired

ID of the parent product.

quantityintrequired

Quantity of the adjustment. A positive number means stock was increased, and a negative number means stock was decreased.

date_createddateauto

Date and time the stock adjustment was created.

date_updateddateauto

Date and time the stock adjustment was last updated.

levelintrequired

New stock level after the adjustment is applied.

numberstringauto

Auto-incremented stock adjustment number.

order_idobjectIdrequired

ID of an order when the stock adjustment was either reduced by the sale of a product, or increased by cancelling an order. Adjustments from orders are created automatically when stock tracking is enabled.

orderOrderrequired

Expandable link to an order, if applicable to the stock adjustment.

parentProduct

Expandable link to the parent product.

reasonenum

Enumerated reason for the stock adjustment. Can be received, returned, canceled, sold, missing, or damaged.

reason_messagestring

A brief description of the reason for the stock adjustment.

variant_idobjectId

ID of the parent variant, if applicable.

variantProduct variant

Expandable link to the parent variant, if applicable.

The stock model
{
  "id": "60f199509111e7000000005f",
  "parent_id": "60f199509111e70000000062",
  "date_created": "2021-07-16T14:36:00.321Z",
  "date_updated": "2021-07-16T14:36:00.321Z",
  "level": 20,
  "number": 1029376,
  "reason": "received",
  "reason_message": "Restock - PO #47362",
  "variant_id": "60f199509111e70000000061"
}

Create a stock adjustment

Create a new stock adjustment. Normally, stock adjustments are automatically created when stock tracking is enabled and orders are placed or canceled.

Arguments

parent_idobjectIdrequired

The id of the parent product.

quantityintrequired

Quantity of the adjustment. A positive number means the stock was increased, and a negative number means the stock was decreased.

reasonstring

Enumerated reason for the stock adjustment. Can be received, returned, canceled, sold, missing, or damaged.

reason_messagestring

A brief description of the reason for the stock adjustment.

POST/products:stock
$ curl https://api.swell.store/products:stock \
  -u store-id:secret-key \
  -d parent_id=5ca24abb9c077817e5fe2b3b
  -d quantity=10
  -d reason=received
  -d reason_message="Restock - PO #47362"
Response
{
  "id": "5ca24abb9c077817e5fe2b3b",
  "parent_id": "5ca7d6c68f749692da37c985",
  "quantity": 10,
  "level": 10,
  "number": "100184",
  "reason": "received"
  "reason_message": "Restock - PO #47362",
  "date_created": "2019-04-01T00:00:00.000Z"
}

Retrieve a stock ajustment

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

Arguments

idobjectIdrequired

The id of the stock adjustment 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 stock adjustment 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:stock/:id
$ curl https://api.swell.store/products:variants/5ca24abb9c077817e5fe2b3b \
  -u store-id:secret-key
Response
{
  "id": "5ca24abb9c077817e5fe2b3b",
  "parent_id": "5ca7d6c68f749692da37c985",
  "quantity": 10,
  "level": 10,
  "number": "100184",
  "reason": "received"
  "reason_message": "Restock - PO #47362",
  "date_created": "2019-04-01T00:00:00.000Z"
  "date_updated": "2019-04-01T00:00:00.000Z",
}

List all stock adjustments

Return a list of product stock adjustments.

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:stock
$ curl https://api.swell.store/products:stock?limit=25&page=1 \
  -u store-id:secret-key \
  -G
Response
{
  "count": 51,
  "results": [
    {
      "id": "60f199509111e7000000005f",
      "parent_id": "60f199509111e70000000066",
      "date_created": "2021-07-16T14:36:00.321Z",
      "date_updated": "2021-07-16T14:36:00.321Z",
      "level": 20,
      "number": 1029376,
      "reason": "received",
      "reason_message": "Restock - PO #47362",
      "variant_id": "60f199509111e70000000061"
    },
    {...},
    {...}
  ],
  "page": 1,
  "pages": {
    "1": {
      "start": 1,
      "end": 25
    },
    "2": {
      "start": 26,
      "end": 50
    },
    "2": {
      "start": 51,
      "end": 51
    }
  }
}

Categories

Categories are used to organize products and can be nested, creating a hierarchy that resembles a tree structure. Since categories aren't necessarily tied to store navigation, you may find uses for categories both visible and invisible to customers.

The category model

Fields

idobjectId

Unique identifier for the category.

namestringrequired

A human-friendly name for the category.

activeboolean

Indicates the category may be visible to customers. Otherwise it will be hidden from view.

childrenCategory

Expandable list of child categories.

date_createddateauto

Date and time the category was created.

date_updateddateauto

Date and time the category was last updated.

descriptionstringrequired

A long-form description of the category. Can contain HTML or other markup languages.

imagesarray of object

List of images depicting the category.

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.

parent_idobjectId

ID of the parent category, if applicable.

parentCategory

Expandable link to the parent category, if applicable.

productsarray of Products

Expandable list of category products.

slugstringrequired

Unique identifier typically used in URLs. Defaults to name converted to lowercase and hyphenated. If the category has a parent, the default slug will be prefixed with the parent slug. Maximum length of 1,000 characters.

sortint

Position of the category in a list.

sortingstring

Default product sorting applied when retrieving products using the category or categories filter. Can be one of popularity, price_asc, price_desc, date_asc. date_desc. If not specified, products are sorted by their manually defined sort value.

top_idobjectId

ID of the top level category in the hierarchy.

topCategory

Expandable link to the top level category.

products_indexedProduct

Expandable list of products as indexed and sorted by their respective position.

The category model
{
  "id": "60f199509111e70000000012",
  "name": "Example category",
  "active": true,
  "date_created": "2021-07-16T14:36:00.084Z",
  "date_updated": "2021-07-16T14:36:00.084Z",
  "description": "A long form description of the category",
  "images": [
    {
      "id": "5cab78ab2045865e3c8a3794",
      "file": {
        "id": "5cab78ab2045865e3c8a375",
        "length": 66764,
        "md5": "99194f53bfdea832553e7fa8ae8fd80f",
        "content_type": "image/png",
        "url": "http://cdn.swell.store/test/5ca24abb9c077817e5fe2b36/99194f53bfdea832553e7fa8ae8fd80f",
        "width": 940,
        "height": 600
      }
    }
  ],
  "meta_description": null,
  "meta_keywords": null,
  "meta_title": null,
  "parent_id": "60f199509111e70000000013",
  "slug": "example-category",
  "sort": 3,
  "sorting": "price_desc",
  "top_id": "60f199509111e70000000014"
}

Create a category

Create a new category.

Arguments

namestringrequired

A human-friendly name for the category.

activeboolean

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

descriptionstring

A long-form description of the category, often containing HTML or other markup languages.

slugstring

Unique identifier typically used in URLs. Defaults to name converted to lowercase and hyphenated. If the category has a parent, the default slug will be prefixed with the parent slug. Maximum length of 1,000 characters.

POST/categories
$ curl https://api.swell.store/categories \
  -u store-id:secret-key \
  -d name=Widgets \
  -d active=true \
Response
{
  "id": "5ca9871f9b14d199072432a1",
  "active": false,
  "name": "Widgets",
  "slug": "widgets",
  "date_created": "2019-04-01T00:00:00.000Z"
}

Retrieve a category

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

Arguments

idobjectIdrequired

The id of the category 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.

etails.

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/categories/:id
$ curl https://api.swell.store/categories/5ca9871f9b14d199072432a1 \
  -u store-id:secret-key
Response
{
  "id": "5ca9871f9b14d199072432a1",
  "active": true,
  "name": "Widgets",
  "slug": "widgets",
  "date_created": "2019-04-01T00:00:00.000Z"
  "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_title": null,
  "meta_keywords": null,
  "meta_description": null
}

Update a category

Arguments

idobjectIdrequired

The unique identifier of the category.

activeboolean

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

descriptionstring

A long-form description of the category, often containing HTML or other markup languages.

namestring

A human-friendly name for the category.

slugstring

Unique identifier typically used in URLs. Defaults to name converted to lowercase and hyphenated. If the category has a parent, the default slug will be prefixed with the parent slug. Maximum length of 1,000 characters.

PUT/categories/:id
$ curl https://api.swell.store/categories/5ca9871f9b14d199072432a1 \
  -u store-id:secret-key \
  -d price=9.99 \
  -X PUT
Response
{
  "id": "5ca9871f9b14d199072432a1",
  "active": false,
  "name": "Widgets",
  "slug": "widgets",
  "date_created": "2019-04-01T00:00:00.000Z"
  "date_updated": "2019-04-01T00:00:00.000Z",
  "description": 'A bunch of widgets',
  "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_title": null,
  "meta_keywords": null,
  "meta_description": null
}

List all categories

Return a list of product categories.

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/categories
$ curl https://api.swell.store/categories?limit=25&page=1 \
  -u store-id:secret-key \
  -G
Response
{
  "count": 51,
  "results": [
    {
      "id": "60f199509111e70000000012",
      "name": "Example category",
      "active": true,
      "date_created": "2021-07-16T14:36:00.084Z",
      "date_updated": "2021-07-16T14:36:00.084Z",
      "description": "A long form description of the category",
      "images": [
        {
          "id": "5cab78ab2045865e3c8a3794",
          "file": {
            "id": "5cab78ab2045865e3c8a375",
            "length": 66764,
            "md5": "99194f53bfdea832553e7fa8ae8fd80f",
            "content_type": "image/png",
            "url": "http://cdn.swell.store/test/5ca24abb9c077817e5fe2b36/99194f53bfdea832553e7fa8ae8fd80f",
            "width": 940,
            "height": 600
          }
        }
      ],
      "meta_description": null,
      "meta_keywords": null,
      "meta_title": null,
      "parent_id": "60f199509111e70000000013",
      "slug": "example-category",
      "sort": 3,
      "sorting": "price_desc",
      "top_id": "60f199509111e70000000014"
    },
    {...},
    {...}
  ],
  "page": 1,
  "pages": {
    "1": {
      "start": 1,
      "end": 25
    },
    "2": {
      "start": 26,
      "end": 50
    },
    "2": {
      "start": 51,
      "end": 51
    }
  }
}

Delete a category

Delete a category.

Arguments

idobjectIdrequired

The id of the category to delete.

DELETE/categories/:id
$ curl https://api.swell.store/categories/5ca9871f9b14d199072432a1 \
  -u store-id:secret-key \
  -X DELETE
Response
{
  "id": "5ca9871f9b14d199072432a1",
  "active": false,
  "name": "Widgets",
  "slug": "widgets",
  "date_created": "2019-04-01T00:00:00.000Z"
  "date_updated": "2019-04-01T00:00:00.000Z",
  "description": 'A bunch of widgets',
  "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_title": null,
  "meta_keywords": null,
  "meta_description": null
}

Attributes

Product attributes are additional characteristics of a product that can be used in different ways. Attributes can be made visible on your detail page with the visible flag or hidden from view. Visible attributes are typically used to display a list of specifications on a detail page. Hidden attributes are typically used as internal data points or to affect the behavior of products in your store theme.

The attribute model

Fields

idstringauto

Unique identifier for the attribute. Defaults to attribute name underscored.

namestring

A human-friendly name for the attribute.

date_createddateauto

Date and time the attribute was created.

date_updateddateauto

Date and time the attribute was last updated.

defaultmixed

Default value used when entering a value for the attribute.

multiboolean

When attribute type=image is indicated, the attribute contains multiple images.

productsProduct

Expandable list of products using the attribute.

requiredboolean

Indicates the attribute requires a value when assigned to a product.

typeenumrequired

Input type used when entering a value for the attribute.

valuesarray of child_scalar

List of values applicable to checkbox, radio, dropdown, and image attributes.

visibleboolean

Indicates the attribute is visible to customers.

Response
{
  "id": "material",
  "name": "Color",
  "date_created": "2021-07-16T14:35:59.968Z",
  "date_updated": "2021-07-16T14:35:59.968Z",
  "default": null,
  "required": false,
  "type": "text",
  "values": [
    "Red",
    "White",
    "Blue",
    "Green",
    "Yellow",
    "Black"
  ],
  "visible": true
}

Create an attribute

Create a new attribute.

Arguments

idobjectIdrequired

Unique identifier for the attribute. Defaults to attribute name underscored.

namestringrequired

A human-friendly name for the attribute.

requiredboolean

Indicates the attribute requires a value when assigned to a product.

typeenum

Input type used when entering a value for the attribute.

valuesarray of child_scalar

List of values applicable to checkbox, radio, dropdown, and image attributes.

visibleboolean

Indicates the attribute is visible to customers.

POST/attributes
$ curl https://api.swell.store/attributes \
  -u store-id:secret-key \
  -d name=Material \
  -d visible=true \
  -d type=dropdown \
  -d values[0]=Cotton \
  -d values[1]=Polyester \
  -d values[2]=Wool
Response
{
  "id": "material",
  "name": "Material",
  "date_created": "2019-04-01T00:00:00.000Z",
  "required": false,
  "visible": true,
  "type": "dropdown",
  "values": [
    "Cotton",
    "Polyester",
    "Wool"
  ]
}

Retrieve an attribute

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

Arguments

idobjectIdrequired

The id of the attribute 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/attributes/:id
$ curl https://api.swell.store/attributes/material \
  -u store-id:secret-key
Response
{
  "id": "material",
  "name": "Material",
  "date_created": "2019-04-01T00:00:00.000Z",
  "required": false,
  "visible": true,
  "type": "dropdown",
  "values": [
    "Cotton",
    "Polyester",
    "Wool"
  ]

Update an attribute

Update an existing attribute 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 attribute. Defaults to attribute name underscored.

namestring

A human-friendly name for the attribute.

requiredboolean

Set true to make the attribute require a value when added to a product.

typeenum

Input type used when entering a value for the attribute.

valuesarray of child_scalar

List of values applicable to checkbox, radio, dropdown, and image attributes.

visibleboolean

Indicates the attribute is visible to customers.

PUT/attributes/:id
$ curl https://api.swell.store/attributes/material \
  -u store-id:secret-key \
  -d required=true \
  -X PUT
Response
{
  "id": "material",
  "name": "Material",
  "date_created": "2019-04-01T00:00:00.000Z",
  "date_updated": "2019-04-01T00:00:00.000Z",
  "required": true,
  "visible": true,
  "type": "dropdown",
  "values": [
    "Cotton",
    "Polyester",
    "Wool"
  ]
}

List all attributes

Return a list of product attributes.

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/attributes
$ curl https://api.swell.store/attributes?limit=25&page=1 \
  -u store-id:secret-key \
  -G
Response
{
  "count": 51,
  "results": [
    {
      "id": "material",
      "name": "Color",
      "date_created": "2021-07-16T14:35:59.968Z",
      "date_updated": "2021-07-16T14:35:59.968Z",
      "default": null,
      "required": false,
      "type": "text",
      "values": [
        "Red",
        "White",
        "Blue",
        "Green",
        "Yellow",
        "Black"
      ],
      "visible": true
    },
    {...},
    {...}
  ],
  "page": 1,
  "pages": {
    "1": {
      "start": 1,
      "end": 25
    },
    "2": {
      "start": 26,
      "end": 50
    },
    "2": {
      "start": 51,
      "end": 51
    }
  }
}

Delete an attribute

Delete an attribute.

Arguments

idobjectIdrequired

The id of the attribute to delete.

DELETE/attributes/:id
$ curl https://api.swell.store/attributes/material \
  -u store-id:secret-key \
  -X DELETE
Response
{
  "id": "material",
  "name": "Material",
  "date_created": "2019-04-01T00:00:00.000Z",
  "date_updated": "2019-04-01T00:00:00.000Z",
  "required": true,
  "visible": true,
  "type": "dropdown",
  "values": [
    "Cotton",
    "Polyester",
    "Wool"
  ]
}

Carts

A cart is a pending request to purchase products from your store. Carts contain all the information needed to fulfill a purchase. Once the customer is ready to complete their purchase, a simple API call is made to convert a cart to an order.

The cart model

Fields

idobjectId

Unique identifier for the cart.

abandonedboolean

Indicates the cart was abandoned after 3 hours of inactivity. After being marked as abandoned, this field is automatically set back to false after an update to items, billing, or shipping info.

abandoned_notificationsint

Number of abandoned cart notifications sent to the customer.

account_idobjectId

ID of the customer's account.

accountCustomer

Expandable link to the customer's account.

account_credit_amountcurrency

Amount of customer's account credit applied for initial payment, if applicable.

account_info_savedboolean

Indicates the customer chose to save shipping and billing information to their account when submitting the order.

account_logged_inboolean

Indicates the customer was logged into their account when placing the order.

activeboolean

Indicates the cart has been updated by a customer within the last 3 hours.

billingobject

The customer's billing details. Defaults to `account.billing`. Updating billing will also update the corresponding account billing object.