API docs
Navbar
API docs
curl Node PHP
Topics
Products
Orders
Subscriptions
Customers
Discounts
Gift cards
Topics

Introduction

Base URL

https://api.swell.store

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

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

Getting started

Use Swell JS for client-side and headless ecommerce.

Swell offers both client-side and server-side APIs. This documentation refers to the server-side API. See the Swell JS library for details on creating client-side and headless ecommerce solutions.

Authentication

Authentication example

$ curl https://client_id:client_key@api.swell.store/products
const swell = require('swell-node').init('store-id', 'secret-key');
<?php $swell = new \Swell\Client('store-id', 'secret-key');

Before using the API, you should create a Swell account.

This account enables access to your store ID and API key which are necessary for API access. To access API keys, follow these steps, beginning on the left sidebar of the admin dashboard.

  1. Navigate to "Admin".
  2. Navigate to "Settings".
  3. Click on "API".
  4. At the top of the page, copy the Store ID.
  5. Under one of the secret keys, click on the eye icon to make the key visible.
  6. Copy the secret key.

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

API authentication differs depending on which library is being used for API access. Refer to the example above 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.

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), andxs 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.

Example validation error

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

Error fields

  • code

    A distinct code indicating the cause of the error, for example `REQUIRED`.

  • message

    A human-readable description of the error.

  • params

    Object containing parameter values related to the error.

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.

try {
  const result = await swell.post(...);
  if (result.errors) {
    // Handle validation errors
  }
} catch (err) {
  // Handle fatal errors
  console.log(err);
}

Querying

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

Query Parameters

  • where object

    An object containing criteria to filter results by.

  • sort string

    A string expression used to sort results.

  • limit int

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

  • page int

    A number indicating which page of results to return.

  • search string

    A string to search and filter results by.

  • expand string or array

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

  • include object

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

Filtering

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
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/products', {
  where: {
    date_created: { $gte: '2018-01-01T00:00:00Z' },
    stock_level: { $gt: 0 },
    active: true,
  },
});
<?php $swell = new \\Swell\\Client('store-id', 'secret-key');

$swell->get('/products', {
  'where' => [
    'date_created' => [ '$gte' => '2018-01-01T00:00:00Z' ],
    'stock_level' => [ '$gt' => 0 ],
    'active' => true
  ]
]);

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.

Sorting

Example query using sort

$ curl https://api.swell.store/products?sort=name+asc
  -u store-id:secret-key
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/products', {
  sort: 'name asc', // or desc
});
<?php $swell = new \\Swell\\Client('store-id', 'secret-key');

$swell->get('/products', {
  'sort' => 'name asc' // or desc
]);

Use the sort parameter to sort results. The format consists of <field> <direction>. Direction is recognized as 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.

Limiting

Example query using limit

$ curl https://api.swell.store/products?limit=100
  -u store-id:secret-key
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/products', {
  limit: 100,
});
<?php $swell = new \\Swell\\Client('store-id', 'secret-key');

$swell->get('/products', {
  'limit' => 100
]);

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.

Pagination

Example query using limit

$ curl https://api.swell.store/products?page=2
  -u store-id:secret-key
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/products', {
  page: 2,
});
<?php $swell = new \\Swell\\Client('store-id', 'secret-key');

$swell->get('/products', {
  'page' => 2
]);

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

Searching

Example query using search

$ curl https://api.swell.store/products?search=blue+shirts
  -u store-id:secret-key
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/products', {
  search: 'blue shirts',
});
<?php $swell = new \\Swell\\Client('store-id', 'secret-key');

$swell->get('/products', {
  'search' => 'blue shirts'
]);

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.

Expanding

Example query using expand

$ curl https://api.swell.store/carts/5407e0929fe97f9d4c712a5e?carts=items.product,items.variant
  -u store-id:secret-key
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/carts/{id}', {
  id: '5407e0929fe97f9d4c712a5e',
  expand: [
    'items.product',
    'items.variant',
  ],
});
<?php $swell = new \\Swell\\Client('store-id', 'secret-key');

$swell->get('/carts/{id}', {
  'id' => '5407e0929fe97f9d4c712a5e',
  'expand' => [
    'items.product',
    'items.variant'
  ]
]);

Example response

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

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, the expand will be performed on all records in the result set.

Including

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
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/orders/{id}', {
  id: '5407e0929fe97f9d4c712a5f',
  include: {
    fulfilled_giftcards: {
      url: '/giftcards',
      params: {
        order_id: 'id',
      },
      data: {
        balance: { $gt: 0 },
      },
    },
  },
});
<?php $swell = new \\Swell\\Client('store-id', 'secret-key');

$swell->get('/orders/{id}', {
  'id' => '5407e0929fe97f9d4c712a5f',
  'include' => [
    'fulfilled_giftcards' => [
      'url' => '/giftcards',
      'params' => [
        'order_id' => 'id'
      ],
      'data' => [
        'balance' => [ '$gt' => 0 ]
      ]
    ]
  ]
]);

Example response

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

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

Aggregation

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
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/orders', {
  aggregate: [
    {
      $match: {
        $and: [
          { date_created: { $gt: '2018-01-01T00:00:00Z' } },
          { date_created: { $lt: '2019-01-01T00:00:00Z' } }
        ]
      }
    },
    {
      $group: {
        count: { $sum: 1 },
        sub_total: { $sum: 'sub_total' },
        avg_total: { $avg: 'sub_total' },
        day: { $dayOfMonth: 'date_created' },
        month: { $month: 'date_created' },
        year: { $year: 'date_created' }
      }
    }
  ]
});
<?php $swell = new \\Swell\\Client('store-id', 'secret-key');

$swell->get('/orders', {
  'aggregate' => [
    [
      '$match' => [
        '$and' => [
          [ 'date_created' => [ '$gt' => '2018-01-01T00:00:00Z' ] ],
          [ 'date_created' => [ '$lt' => '2019-01-01T00:00:00Z' ] ]
        ]
      ]
    ],
    [
      '$group' => [
        'count' => [ '$sum' => 1 ],
        'sub_total' => [ '$sum' => 'sub_total' ],
        'avg_total' => [ '$avg' => 'sub_total' ],
        'day' => [ '$dayOfMonth' => 'date_created' ],
        'month' => [ '$month' => 'date_created' ],
        'year' => [ '$year' => 'date_created' ]
      ]
    ]
  ]
]);

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

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

Example webhook payload

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

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.

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

Products

Products

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

The product model

The product object

{
  "id": "5f626b0d91f0af999b00006a",
  "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": "2020-09-16T19:44:13.799Z",
  "date_updated": "2020-09-16T19:44:13.799Z",
  "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_price": 19.99,
  "sale": false,
  "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
}

Fields

  • id objectid

    Unique identifier for the product.

  • name string

    Human-friendly name of the product.

  • active bool, default: false

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

  • attributes object

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

  • bundle_items array

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

    Show bundle_items fields
    • bundle_items.id objectid

      Unique identifier for the bundle item.

    • bundle_items.product_id objectid

      ID of the bundled product.

    • bundle_items.product link

      Expandable link to the bundled product.

    • bundle_items.quantity int

      Quantity of the bundled product. Defaults to 1.

    • bundle_items.variant link

      Expandable link to the bundled product variant, if applicable.

    • bundle_items.variant_id objectid

      ID of the bundled variant, if applicable.

  • bundle bool

    Indicates whether the product is a bundle of other products.

  • categories link

    Expandable link to all related product categories.

  • category_id objectid

    Primary category, commonly used as a navigation anchor.

  • category_index auto object

    Index of categories used for fast lookup operations.

    Show category_index fields
    • category_index.id array

      List of related product category IDs.

    • category_index.sort object

      Index of category IDs and their respective sort positions.

  • category link

    Expandable link to the primary category.

  • cost currency

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

  • cross_sells array

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

    Show cross_sells fields
    • cross_sells.id objectid

      Unique identifier for the cross-sell object.

    • cross_sells.product_id objectid

      ID of the cross-sell product.

    • cross_sells.discount_amount currency

      Discount to apply as a fixed amount. Applicable only when discount_type=fixed.

    • cross_sells.discount_percent float

      Discount to apply as a percentage. Applicable only when discount_type=percent.

    • cross_sells.discount_type string

      Type of discount to apply, either fixed or percent.

    • cross_sells.product link

      Expandable link to the cross-sell product.

  • currency auto string

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

  • customizable bool

    Indicates whether the product has custom options enabled.

  • date_created auto date

    Date and time the product was created.

  • date_updated auto date

    Date and time the product was last updated.

  • delivery auto string

    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.

  • description string

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

  • images array

    List of images depicting the bundle.

    Show images fields
    • images.id objectid

      Unique identifier for the image.

    • images.caption string

      A brief description of the image, intended for display as a caption or alt text.

    • images.file file

      An object representing the image's source file.

      Show file fields
      • images.file.id objectid

        Unique identifier for the file.

      • images.file.content_type string

        MIME content type of the file.

      • images.file.data filedata

        A reference to the raw file data.

      • images.file.date_uploaded date

        Date the file was uploaded.

      • images.file.filename string

        Optional file name.

      • images.file.height int

        Image height in pixels, if applicable.

      • images.file.length int

        Size of the file in bytes.

      • images.file.md5 string

        An MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes.

      • images.file.url string

        A public URL to reference the file. Updated automatically if file content changes.

      • images.file.width int

        Image width in pixels, if applicable.

  • meta_description string

    Page description used for search engine optimization purposes.

  • meta_keywords string

    Page keywords used for search engine optimization purposes.

  • meta_title string

    Page title used to override product name in storefronts.

  • options array

    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.

    Show options fields
    • options.id objectid

      Unique identifier for the object.

    • options.name string

      Human-friendly name of the option.

    • options.input_hint string

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

    • options.input_type string

      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_id objectid

      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_ids array

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

    • options.price currency

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

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

    • options.subscription bool

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

    • options.values array

      List of possible values for this option.

      Show values fields
      • options.values.id objectid

        Unique identifier for the object.

      • options.values.name string

        Human-friendly name of the option value.

      • options.values.description string

        A brief description of the option value, intended for displaying to customers.

      • options.values.images array

        One or more images depicting the option value.

        Show images fields
        • options.values.images.id objectid

          Unique identifier for the image.

        • options.values.images.caption string

          A brief description of the image, intended for display as a caption or alt text.

        • options.values.images.file file

          An object representing the image's source file.

          Show file fields
          • images.file.id objectid

            Unique identifier for the file.

          • images.file.content_type string

            MIME content type of the file.

          • images.file.data filedata

            A reference to the raw file data.

          • images.file.date_uploaded date

            Date the file was uploaded.

          • images.file.filename string

            Optional file name.

          • images.file.height int

            Image height in pixels, if applicable.

          • images.file.length int

            Size of the file in bytes.

          • images.file.md5 string

            An MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes.

          • images.file.url string

            A public URL to reference the file. Updated automatically if file content changes.

          • images.file.width int

            Image width in pixels, if applicable.

      • options.values.price currency

        Extra price added to the product's price/sale_price if the option value is selected. Overrides option price.

      • options.values.shipment_weight float

        Extra weight added to the product's shipment_weight if the option value is selected. The unit should match the store's default as configured in general settings.

      • options.values.subscription_interval_count int

        When product type=subscription, this number multiplies subscription_interval to determine the billing frequency when this option is selected. For example, to make a subscription bill every 2 weeks, set subscription_interval=weekly and subscription_interval_count=2.

      • options.values.subscription_interval string

        When product type=subscription, this is the billing interval used when this option value is selected. Can be monthly, yearly, weekly or daily.

      • options.values.subscription_trial_days int

        When product type=subscription, refers to a number of days offered as a trial before an invoice is issued.

    • options.variant bool

      Indicates whether the option is part of a variant. Variants are automatically generated or archived based on all options with this value set to true.

  • price currency

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

  • prices array

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

    Show prices fields
    • prices.price currency

      Price applied when conditions are met.

    • prices.account_group string

      Customer account group as a condition to apply price.

    • prices.quantity_max int

      Maximum quantity as a condition to apply price.

    • prices.quantity_min int

      Minimum quantity as a condition to apply price.

  • quantity_inc int

    Specifies a quantify multiple the product must be sold in.

  • quantity_min int

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

  • review_rating auto float

    Average rating from all product reviews.

  • reviews collection

    Expandable list of product reviews.

  • sale_price currency

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

  • sale bool

    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.

  • shipment_dimensions object

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

    Show shipment_dimensions fields
    • shipment_dimensions.height float

      Height of the product in unit.

    • shipment_dimensions.length float

      Length of the product in unit.

    • shipment_dimensions.unit string

      Either in (inches) or cm (centimeters).

    • shipment_dimensions.width float

      Width of the product in unit.

  • shipment_location string

    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_quantity float

    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_prices array

    Product shipping price rules to override default shipping rules.

    Show shipment_prices fields
    • shipment_prices.service string

      Shipping service required for this rule to apply.

    • shipment_prices.account_group string

      Customer group required for this rule to apply.

    • shipment_prices.country string

      Shipping country required for this rule to apply.

    • shipment_prices.fee_amount currency

      Fixed amount to add when rule is applied. Only applicable when fee_type=fixed.

    • shipment_prices.fee_percent float

      Percentage of the shipping price to add when rule is applied. Only applicable when fee_type=percent.

    • shipment_prices.fee_type string

      Type of fee to apply in addition to price, either fixed or percent.

    • shipment_prices.package_quantity int

      Maximum package quantity when rule is applied.

    • shipment_prices.price currency

      Shipping price when rule is applied.

    • shipment_prices.state string

      Shipping state required for this rule to apply.

    • shipment_prices.total_max currency

      Maximum order subtotal for this rule to apply.

    • shipment_prices.total_min currency

      Minimum order subtotal for this rule to apply.

    • shipment_prices.weight_max float

      Maximum order item weight for this rule to apply.

    • shipment_prices.weight_min float

      Minimum order item weight for this rule to apply.

    • shipment_prices.zip string

      Shipping zip/postal code required for this rule to apply.

  • shipment_weight float

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

  • sku string

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

  • slug string, unique

    Lowercase, hyphenated identifier typically used in URLs. When creating a product, a slug will be generated automatically from the name.

  • stock_level int, default: 0

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

  • stock collection

    Expandable list of stock adjustments for the product.

  • stock_status auto string

    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_tracking bool

    Indicates whether the product has stock tracking enabled.

  • subscription_interval string

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

  • subscription_interval_count int

    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_days int

    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.

  • tags array

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

  • type string, default: standard

    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_sells array

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

    Show up_sells fields
    • up_sells.id objectid

      Unique identifier for the up-sell.

    • up_sells.product_id objectid

      ID of the up-sell product.

    • up_sells.product link

      Expandable link to the up-sell product.

  • variable bool

    Indicates whether the product has variant generation enabled.

  • variants collection

    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.

Create a product

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
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.post('/products', {
  name: 'T-Shirt',
  price: 99.00,
  active: true,
  options: [
    {
      name: 'Size',
      values: [
        {
          name: 'Small',
        },
        {
          name: 'Large',
        },
      ],
    },
    {...},
  ],
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->post('/products', [
  'name' => 'T-Shirt',
  'price' => 99.00,
  'active' => true,
  'options' => [
    [
      'name' => 'Size',
      'values' => [
        [
          'name' => 'Small',
        ],
        [
          'name' => 'Large',
        ],
      ],
    ],
    [...],
  ],
]);

Example 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"
}

Create a new product.

Arguments

  • name required

    Human-friendly name of the product.

  • attributes optional

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

  • price optional

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

  • slug optional

    Lowercase, hyphenated identifier typically used in URLs. When creating a product, a slug will be generated automatically from the name.

  • type optional

    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.

  • Show all arguments
    • active optional

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

    • bundle_items optional

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

      Show bundle_items arguments
      • bundle_items.product_id optional

        ID of the bundled product.

      • bundle_items.quantity optional

        Quantity of the bundled product. Defaults to 1.

      • bundle_items.variant_id optional

        ID of the bundled variant, if applicable.

    • bundle optional

      Indicates whether the product is a bundle of other products.

    • category_id optional

      Primary category, commonly used as a navigation anchor.

    • cost optional

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

    • cross_sells optional

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

      Show cross_sells arguments
      • cross_sells.product_id optional

        ID of the cross-sell product.

      • cross_sells.discount_amount optional

        Discount to apply as a fixed amount. Applicable only when discount_type=fixed.

      • cross_sells.discount_percent optional

        Discount to apply as a percentage. Applicable only when discount_type=percent.

      • cross_sells.discount_type optional

        Type of discount to apply, either fixed or percent.

    • customizable optional

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

    • description optional

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

    • images optional

      List of images depicting the bundle.

      Show images arguments
      • images.caption optional

        A brief description of the image, intended for display as a caption or alt text.

      • images.file optional

        An object representing the image's source file.

        Show file arguments
        • images.file.data optional

          Set or overwrite file data. Use the following format when writing a file from binary data (for example an image): data[$binary]=<base64 encoded binary daya>.

        • images.file.filename optional

          Optional file name.

    • meta_description optional

      Page description used for search engine optimization purposes.

    • meta_keywords optional

      Page keywords used for search engine optimization purposes.

    • meta_title optional

      Page title used to override product name in storefronts.

    • options optional

      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.

      Show options arguments
      • options.name optional

        Human-friendly name of the option.

      • options.input_hint optional

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

      • options.input_type optional

        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_id optional

        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_ids optional

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

      • options.price optional

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

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

        List of possible values for this option.

        Show values arguments
        • options.values.name optional

          Human-friendly name of the option value.

        • options.values.description optional

          A brief description of the option value, intended for displaying to customers.

        • options.values.images optional

          One or more images depicting the option value.

          Show images arguments
          • options.values.images.caption optional

            A brief description of the image, intended for display as a caption or alt text.

          • options.values.images.file optional

            An object representing the image's source file.

            Show file arguments
            • images.file.data optional

              Set or overwrite file data. Use the following format when writing a file from binary data (for example an image): data[$binary]=<base64 encoded binary daya>.

            • images.file.filename optional

              Optional file name.

        • options.values.price optional

          Extra price added to the product's price/sale_price if the option value is selected. Overrides option price.

        • options.values.shipment_weight optional

          Extra weight added to the product's shipment_weight if the option value is selected. The unit should match the store's default as configured in general settings.

        • options.values.subscription_interval_count optional

          When product type=subscription, this number multiplies subscription_interval to determine the billing frequency when this option is selected. For example, to make a subscription bill every 2 weeks, set subscription_interval=weekly and subscription_interval_count=2.

        • options.values.subscription_interval optional

          When product type=subscription, this is the billing interval used when this option value is selected. Can be monthly, yearly, weekly or daily.

        • options.values.subscription_trial_days optional

          When product type=subscription, refers to a number of days offered as a trial before an invoice is issued.

      • options.variant optional

        Set true to generate variants including this option.

    • prices optional

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

      Show prices arguments
      • prices.price optional

        Set price to apply when conditions are met.

      • prices.account_group optional

        Customer account group as a condition to apply price.

      • prices.quantity_max optional

        Maximum quantity as a condition to apply price.

      • prices.quantity_min optional

        Minimum quantity as a condition to apply price.

    • quantity_inc optional

      Specifies a quantify multiple the product must be sold in.

    • quantity_min optional

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

    • sale optional

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

    • sale_price optional

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

    • shipment_dimensions optional

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

      Show shipment_dimensions arguments
      • shipment_dimensions.height optional

        Height of the product in unit.

      • shipment_dimensions.length optional

        Length of the product in unit.

      • shipment_dimensions.unit optional

        Either in (inches) or cm (centimeters).

      • shipment_dimensions.width optional

        Width of the product in unit.

    • shipment_location optional

      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_quantity optional

      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_prices optional

      Product shipping price rules to override default shipping rules.

      Show shipment_prices arguments
      • shipment_prices.service optional

        Shipping service required for this rule to apply.

      • shipment_prices.account_group optional

        Customer group required for this rule to apply.

      • shipment_prices.country optional

        Shipping country required for this rule to apply.

      • shipment_prices.fee_amount optional

        Fixed amount to add when rule is applied. Only applicable when fee_type=fixed.

      • shipment_prices.fee_percent optional

        Percentage of the shipping price to add when rule is applied. Only applicable when fee_type=percent.

      • shipment_prices.fee_type optional

        Type of fee to apply in addition to price, either fixed or percent.

      • shipment_prices.package_quantity optional

        Maximum package quantity when rule is applied.

      • shipment_prices.price optional

        Shipping price when rule is applied.

      • shipment_prices.state optional

        Shipping state required for this rule to apply.

      • shipment_prices.total_max optional

        Maximum order subtotal for this rule to apply.

      • shipment_prices.total_min optional

        Minimum order subtotal for this rule to apply.

      • shipment_prices.weight_max optional

        Maximum order item weight for this rule to apply.

      • shipment_prices.weight_min optional

        Minimum order item weight for this rule to apply.

      • shipment_prices.zip optional

        Shipping zip/postal code required for this rule to apply.

    • shipment_weight optional

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

    • sku optional

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

    • stock_tracking optional

      Set true to enable stock tracking this product.

    • subscription_interval_count optional

      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_interval optional

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

    • subscription_trial_days optional

      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.

    • tags optional

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

    • up_sells optional

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

      Show up_sells arguments
      • up_sells.product_id optional

        ID of the up-sell product.

    • variable optional

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

Returns

Returns a new product if valid arguments are provided, otherwise returns an object containing validation errors.

Retrieve a product

GET /products/:id

$ curl https://api.swell.store/products/5c8fb5e1ed2faf8c79da492a \
  -u store-id:secret-key
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/products/{id}', {
  id: '5c8fb5e1ed2faf8c79da492a',
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->get('/products/{id}', [
  'id' => '5c8fb5e1ed2faf8c79da492a',
]);

Example 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"
}

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

Arguments

  • id required

    ID of the product to retrieve.

  • expand optional

    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.

  • fields optional

    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 product id is always returned.

  • include optional

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

Returns

Returns a product if a valid ID was provided. Otherwise null.

Update a product

PUT /products/:id

$ curl https://api.swell.store/products/5c8fb5e1ed2faf8c79da492a \
  -u store-id:secret-key \
  -d price=9.99 \
  -X PUT
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.put('/products/{id}', {
  id: '5c8fb5e1ed2faf8c79da492a',
  price: 19.98,
  // use $set to override values
  $set: {
    options: [
      ...
    ],
  },
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->put('/products/{id}', [
  'id' => '5c8fb5e1ed2faf8c79da492a',
  'price' => 19.98,
  // use $set to override values
  '$set' => {
    'options' => [
      ...
    ],
  ],
]);

Example 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"
}

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

  • id required

    Unique identifier for the product.

  • active optional

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

  • attributes optional

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

  • name optional

    Human-friendly name of the product.

  • price optional

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

  • slug optional

    Lowercase, hyphenated identifier typically used in URLs. When creating a product, a slug will be generated automatically from the name.

  • Show all arguments
    • bundle optional

      Indicates whether the product is a bundle of other products.

    • bundle_items optional

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

      Show bundle_items arguments
      • bundle_items.product_id optional

        ID of the bundled product.

      • bundle_items.quantity optional

        Quantity of the bundled product. Defaults to 1.

      • bundle_items.variant_id optional

        ID of the bundled variant, if applicable.

    • category_id optional

      Primary category, commonly used as a navigation anchor.

    • cost optional

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

    • cross_sells optional

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

      Show cross_sells arguments
      • cross_sells.product_id optional

        ID of the cross-sell product.

      • cross_sells.discount_amount optional

        Discount to apply as a fixed amount. Applicable only when discount_type=fixed.

      • cross_sells.discount_percent optional

        Discount to apply as a percentage. Applicable only when discount_type=percent.

      • cross_sells.discount_type optional

        Type of discount to apply, either fixed or percent.

    • customizable optional

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

    • description optional

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

    • images optional

      List of images depicting the bundle.

      Show images arguments
      • images.caption optional

        A brief description of the image, intended for display as a caption or alt text.

      • images.file optional

        An object representing the image's source file.

        Show file arguments
        • images.file.data optional

          Set or overwrite file data. Use the following format when writing a file from binary data (for example an image): data[$binary]=<base64 encoded binary daya>.

        • images.file.filename optional

          Optional file name.

    • meta_description optional

      Page description used for search engine optimization purposes.

    • meta_keywords optional

      Page keywords used for search engine optimization purposes.

    • meta_title optional

      Page title used to override product name in storefronts.

    • options optional

      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.

      Show options arguments
      • options.name optional

        Human-friendly name of the option.

      • options.input_hint optional

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

      • options.input_type optional

        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_id optional

        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_ids optional

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

      • options.price optional

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

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

        List of possible values for this option.

        Show values arguments
        • options.values.name optional

          Human-friendly name of the option value.

        • options.values.description optional

          A brief description of the option value, intended for displaying to customers.

        • options.values.images optional

          One or more images depicting the option value.

          Show images arguments
          • options.values.images.caption optional

            A brief description of the image, intended for display as a caption or alt text.

          • options.values.images.file optional

            An object representing the image's source file.

            Show file arguments
            • images.file.data optional

              Set or overwrite file data. Use the following format when writing a file from binary data (for example an image): data[$binary]=<base64 encoded binary daya>.

            • images.file.filename optional

              Optional file name.

        • options.values.price optional

          Extra price added to the product's price/sale_price if the option value is selected. Overrides option price.

        • options.values.shipment_weight optional

          Extra weight added to the product's shipment_weight if the option value is selected. The unit should match the store's default as configured in general settings.

        • options.values.subscription_interval_count optional

          When product type=subscription, this number multiplies subscription_interval to determine the billing frequency when this option is selected. For example, to make a subscription bill every 2 weeks, set subscription_interval=weekly and subscription_interval_count=2.

        • options.values.subscription_interval optional

          When product type=subscription, this is the billing interval used when this option value is selected. Can be monthly, yearly, weekly or daily.

        • options.values.subscription_trial_days optional

          When product type=subscription, refers to a number of days offered as a trial before an invoice is issued.

      • options.variant optional

        Set true to generate variants including this option.

    • prices optional

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

      Show prices arguments
      • prices.price optional

        Set price to apply when conditions are met.

      • prices.account_group optional

        Customer account group as a condition to apply price.

      • prices.quantity_max optional

        Maximum quantity as a condition to apply price.

      • prices.quantity_min optional

        Minimum quantity as a condition to apply price.

    • quantity_inc optional

      Specifies a quantify multiple the product must be sold in.

    • quantity_min optional

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

    • sale_price optional

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

    • sale optional

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

    • shipment_dimensions optional

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

      Show shipment_dimensions arguments
      • shipment_dimensions.height optional

        Height of the product in unit.

      • shipment_dimensions.length optional

        Length of the product in unit.

      • shipment_dimensions.unit optional

        Either in (inches) or cm (centimeters).

      • shipment_dimensions.width optional

        Width of the product in unit.

    • shipment_location optional

      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_quantity optional

      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_prices optional

      Product shipping price rules to override default shipping rules.

      Show shipment_prices arguments
      • shipment_prices.service optional

        Shipping service required for this rule to apply.

      • shipment_prices.account_group optional

        Customer group required for this rule to apply.

      • shipment_prices.country optional

        Shipping country required for this rule to apply.

      • shipment_prices.fee_amount optional

        Fixed amount to add when rule is applied. Only applicable when fee_type=fixed.

      • shipment_prices.fee_percent optional

        Percentage of the shipping price to add when rule is applied. Only applicable when fee_type=percent.

      • shipment_prices.fee_type optional

        Type of fee to apply in addition to price, either fixed or percent.

      • shipment_prices.package_quantity optional

        Maximum package quantity when rule is applied.

      • shipment_prices.price optional

        Shipping price when rule is applied.

      • shipment_prices.state optional

        Shipping state required for this rule to apply.

      • shipment_prices.total_max optional

        Maximum order subtotal for this rule to apply.

      • shipment_prices.total_min optional

        Minimum order subtotal for this rule to apply.

      • shipment_prices.weight_max optional

        Maximum order item weight for this rule to apply.

      • shipment_prices.weight_min optional

        Minimum order item weight for this rule to apply.

      • shipment_prices.zip optional

        Shipping zip/postal code required for this rule to apply.

    • shipment_weight optional

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

    • sku optional

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

    • stock_tracking optional

      Set true to enable stock tracking this product.

    • subscription_interval_count optional

      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_interval optional

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

    • subscription_trial_days optional

      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.

    • tags optional

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

    • type optional

      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_sells optional

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

      Show up_sells arguments
      • up_sells.product_id optional

        ID of the up-sell product.

    • variable optional

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

Returns

Returns the updated product if valid arguments are provided, otherwise returns an object containing validation errors.

List all products

GET /products

$ curl https://api.swell.store/products?where[active]=true&limit=25&page=1 \
  -u store-id:secret-key \
  -G
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/products', {
  where: { active: true },
  limit: 25,
  page: 1,
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->get('/products', [
  'where' => [ 'active' => true ],
  'limit' => 25,
  'page' => 1,
]);

Example 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
    }
  }
}

Return a list of products.

Arguments

  • expand optional

    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.

  • fields optional

    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 product id is always returned.

  • include optional

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

  • limit optional

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

  • page optional

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

  • search optional

    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.

  • sort optional

    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.

  • where optional

    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.

Returns

An object with an array of results containing up to the limit and matching filters specified. If no records are found given the page and limit arguments, the results array will be empty. This request should never throw an error.

Delete a product

DELETE /products/:id

$ curl https://api.swell.store/products/5c8fb5e1ed2faf8c79da492a \
  -u store-id:secret-key \
  -X DELETE
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.delete('/products/{id}', {
  id: '5c8fb5e1ed2faf8c79da492a',
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->delete('/products/{id}', [
  'id' => '5c8fb5e1ed2faf8c79da492a',
]);

Example 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"
}

Delete a product. Try to avoid deleting products that have been sold to a customer, as the link to existing orders will be broken. Note: when deleting a record that has child collections such as variants and stock, the contents of those collections are also deleted.

Arguments

  • id required

    ID of the product to delete.

Returns

Returns the original product if the operation was successful, or null if the product was not found.

Variants

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

The variant model

The variant object

{
  "id": "5f626b0d91f0af999b000067",
  "name": "Medium",
  "parent_id": "5f626b0d91f0af999b000069",
  "active": true,
  "archived": false,
  "attributes": {
    "example": true
  },
  "currency": "USD",
  "date_created": "2020-09-16T19:44:13.777Z",
  "date_updated": "2020-09-16T19:44:13.777Z",
  "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
}

Fields

  • id objectid

    Unique identifier for the variant.

  • name string

    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_id objectid

    ID of the parent product.

  • active bool, default: false

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

  • archived bool

    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.

  • attributes object

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

  • cost currency

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

  • currency auto string

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

  • date_created auto date

    Date and time the variant was created.

  • date_updated auto date

    Date and time the variant was last updated.

  • images array

    List of images depicting the variant.

    Show images fields
    • images.id objectid

      Unique identifier for the object.

    • images.caption string

      A brief description of the image.

    • images.file file

      An object representing the image file.

      Show file fields
      • images.file.id objectid

        Unique identifier for the file.

      • images.file.content_type string

        MIME content type of the file.

      • images.file.data filedata

        A reference to the raw file data.

      • images.file.date_uploaded date

        Date the file was uploaded.

      • images.file.filename string

        Optional file name.

      • images.file.height int

        Image height in pixels, if applicable.

      • images.file.length int

        Size of the file in bytes.

      • images.file.md5 string

        An MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes.

      • images.file.url string

        A public URL to reference the file. Updated automatically if file content changes.

      • images.file.width int

        Image width in pixels, if applicable.

  • option_value_ids array

    List of option value IDs that constitute the variant.

  • parent link

    Expandable link to the parent product.

  • prices array

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

    Show prices fields
    • prices.price currency

      Price applied when conditions are met.

    • prices.account_group string

      Customer account group as a condition to apply price.

    • prices.quantity_max int

      Maximum quantity as a condition to apply price.

    • prices.quantity_min int

      Minimum quantity as a condition to apply price.

  • price currency

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

  • sale bool

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

  • sale_price currency

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

  • shipment_weight float

    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 product shipping weight.

  • sku string

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

  • stock_level int

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

Create a variant

POST /products:variants

$ curl https://api.swell.store/products:variants \
  -u store-id:secret-key \
  -d parent_id=5ca24abb9c077817e5fe2b36
  -d name="Blue, Small"
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.post('/products:variants', {
  parent_id: '5ca24abb9c077817e5fe2b36',
  name: 'Blue, Small',
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->post('/products:variants', [
  'parent_id' => '5ca24abb9c077817e5fe2b36',
  'name' => 'Blue, Small',
]);

Example response

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

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

Arguments

  • name required

    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_id required

    ID of the parent product.

  • attributes optional

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

  • option_value_ids optional

    List of option value IDs that constitute the variant.

  • price optional

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

  • Show all arguments
    • active optional

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

    • archived optional

      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.

    • cost optional

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

    • images optional

      List of images depicting the variant.

      Show images arguments
      • images.caption optional

        A brief description of the image.

      • images.file optional

        An object representing the image file.

        Show file arguments
        • images.file.data optional

          Set or overwrite file data. Use the following format when writing a file from binary data (for example an image): data[$binary]=<base64 encoded binary daya>.

        • images.file.filename optional

          Optional file name.

    • prices optional

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

      Show prices arguments
      • prices.price optional

        Price applied when conditions are met.

      • prices.account_group optional

        Customer account group as a condition to apply price.

      • prices.quantity_max optional

        Maximum quantity as a condition to apply price.

      • prices.quantity_min optional

        Minimum quantity as a condition to apply price.

    • sale_price optional

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

    • sale optional

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

    • shipment_weight optional

      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 product shipping weight.

    • sku optional

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

Returns

Returns a new variant if valid arguments are provided, otherwise returns an object containing validation errors.

Retrieve a variant

GET /products:variants/:id

$ curl https://api.swell.store/products:variants/5c8fb5e1ed2faf8c79da492a \
  -u store-id:secret-key
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/products:variants/{id}', {
  id: '5c8fb5e1ed2faf8c79da492a',
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->get('/products:variants/{id}', [
  'id' => '5c8fb5e1ed2faf8c79da492a',
]);

Example 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",
}

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

Arguments

  • id required

    ID of the variant to retrieve.

  • expand optional

    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.

  • fields optional

    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.

  • include optional

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

Returns

Returns a variant if a valid ID was provided. Otherwise null.

Update a variant

PUT /products:variants/:id

$ curl https://api.swell.store/products:variants/5c8fb5e1ed2faf8c79da492a \
  -u store-id:secret-key \
  -d price=19.98 \
  -X PUT
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.put('/products:variants/{id}', {
  id: '5c8fb5e1ed2faf8c79da492a',
  price: 19.98,
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->put('/products:variants/{id}', [
  'id' => '5c8fb5e1ed2faf8c79da492a',
  'price' => 19.98,
]);

Example 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
}

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

  • id required

    Unique identifier for the variant.

  • parent_id required

    ID of the parent product.

  • active optional

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

  • attributes optional

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

  • name optional

    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.

  • price optional

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

  • Show all arguments
    • archived optional

      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.

    • cost optional

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

    • images optional

      List of images depicting the variant.

      Show images arguments
      • images.caption optional

        A brief description of the image.

      • images.file optional

        An object representing the image file.

        Show file arguments
        • images.file.data optional

          Set or overwrite file data. Use the following format when writing a file from binary data (for example an image): data[$binary]=<base64 encoded binary daya>.

        • images.file.filename optional

          Optional file name.

    • prices optional

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

      Show prices arguments
      • prices.price optional

        Price applied when conditions are met.

      • prices.account_group optional

        Customer account group as a condition to apply price.

      • prices.quantity_max optional

        Maximum quantity as a condition to apply price.

      • prices.quantity_min optional

        Minimum quantity as a condition to apply price.

    • sale_price optional

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

    • sale optional

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

    • shipment_weight optional

      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 product shipping weight.

    • sku optional

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

Returns

Returns the updated variant if valid arguments are provided, otherwise returns an object containing validation errors.

List all variants

GET /products:variants

$ curl https://api.swell.store/products:variants?where[active]=true&limit=25&page=1 \
  -u store-id:secret-key \
  -G
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/products:variants', {
  where: { active: true },
  limit: 25,
  page: 1,
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->get('/products:variants', [
  'where' => [ 'active' => true ],
  'limit' => 25,
  'page' => 1,
]);

Example 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
    }
  }
}

Return a list of product variants.

Arguments

  • expand optional

    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.

  • fields optional

    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.

  • include optional

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

  • limit optional

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

  • page optional

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

  • search optional

    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.

  • sort optional

    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.

  • where optional

    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.

Returns

An object with an array of results containing up to the limit and matching filters specified. If no records are found given the page and limit arguments, the results array will be empty. This request should never throw an error.

Delete a variant

DELETE /products:variants/:id

$ curl https://api.swell.store/products:variants/5c8fb5e1ed2faf8c79da492a \
  -u store-id:secret-key \
  -X DELETE
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.delete('/products:variants/{id}', {
  id: '5c8fb5e1ed2faf8c79da492a',
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->delete('/products:variants/{id}', [
  'id' => '5c8fb5e1ed2faf8c79da492a',
]);

Example 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
}

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

  • id required

    ID of the variant to delete.

Returns

Returns the original variant if the operation was successful, or null if the variant was not found.

Stock

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

The stock model

The stock adjustment object

{
  "id": "5f626b0d91f0af999b00005f",
  "parent_id": "5f626b0d91f0af999b000062",
  "date_created": "2020-09-16T19:44:13.773Z",
  "date_updated": "2020-09-16T19:44:13.773Z",
  "level": 20,
  "number": 1029376,
  "reason_message": "Restock - PO #47362",
  "reason": "received",
  "variant_id": "5f626b0d91f0af999b000061"
}

Fields

  • id objectid

    Unique identifier for the stock adjustment.

  • parent_id objectid

    ID of the parent product.

  • quantity int

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

  • date_created auto date

    Date and time the stock adjustment was created.

  • date_updated auto date

    Date and time the stock adjustment was last updated.

  • level auto int

    New stock level after the adjustment is applied.

  • number auto string

    Auto-incremented stock adjustment number.

  • order link

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

  • order_id objectid

    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.

  • parent link

    Expandable link to the parent product.

  • reason_message string

    A brief description of the reason for the stock adjustment.

  • reason string

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

  • variant_id objectid

    ID of the parent variant, if applicable.

  • variant link

    Expandable link to the parent variant, if applicable.

Create a 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"
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.post('/products:stock', {
  parent_id: '5ca24abb9c077817e5fe2b3b',
  quantity: 10,
  reason: 'received',
  reason_message: 'Restock - PO #47362',
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->post('/products:stock', [
  'parent_id' => '5ca24abb9c077817e5fe2b3b',
  'quantity' => 10,
  'reason_message' => 'Restock - PO #47362'
]);

Example 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"
}

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

Arguments

  • parent_id required

    ID of the parent product.

  • quantity required

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

  • reason_message optional

    A brief description of the reason for the stock adjustment.

  • reason optional

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

  • Show all arguments
    • order_id optional

      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.

    • variant_id optional

      ID of the parent variant, if applicable.

Returns

Returns a new stock adjustment if valid arguments are provided, otherwise returns an object containing validation errors.

Retrieve a stock adjustment

GET /products:stock/:id

$ curl https://api.swell.store/products:variants/5ca24abb9c077817e5fe2b3b \
  -u store-id:secret-key
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/products:stock/{id}', {
  id: '5ca24abb9c077817e5fe2b3b',
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->get('/products:stock/{id}', [
  'id' => '5ca24abb9c077817e5fe2b3b',
]);

Example 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",
}

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

Arguments

  • id required

    ID of the stock adjustment to retrieve.

  • expand optional

    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.

  • fields optional

    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.

  • include optional

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

Returns

Returns a stock adjustment if a valid ID was provided. Otherwise null.

List all stock adjustments

GET /products:stock

$ curl https://api.swell.store/products:stock?limit=25&page=1 \
  -u store-id:secret-key \
  -G
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/products:stock', {
  limit: 25,
  page: 1
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->get('/products:stock', [
  'limit' => 25,
  'page' => 1
]);

Example response

{
  "count": 51,
  "results": [
    {
      "id": "5f626b0d91f0af999b00005f",
      "parent_id": "5f626b0d91f0af999b000066",
      "date_created": "2020-09-16T19:44:13.773Z",
      "date_updated": "2020-09-16T19:44:13.773Z",
      "level": 20,
      "number": 1029376,
      "reason_message": "Restock - PO #47362",
      "reason": "received",
      "variant_id": "5f626b0d91f0af999b000061"
    },
    {...},
    {...}
  ],
  "page": 1,
  "pages": {
    "1": {
      "start": 1,
      "end": 25
    },
    "2": {
      "start": 26,
      "end": 50
    },
    "2": {
      "start": 51,
      "end": 51
    }
  }
}

Return a list of product stock adjustments.

Arguments

  • expand optional

    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.

  • fields optional

    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.

  • include optional

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

  • limit optional

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

  • page optional

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

  • search optional

    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.

  • sort optional

    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.

  • where optional

    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.

Returns

An object with an array of results containing up to the limit and matching filters specified. If no records are found given the page and limit arguments, the results array will be empty. This request should never throw an error.

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

The category object

{
  "id": "5f626b0d91f0af999b000012",
  "name": "Example category",
  "active": true,
  "date_created": "2020-09-16T19:44:13.642Z",
  "date_updated": "2020-09-16T19:44:13.642Z",
  "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": "5f626b0d91f0af999b000013",
  "slug": "example-category",
  "sort": 3,
  "sorting": "price_desc",
  "top_id": "5f626b0d91f0af999b000014"
}

Fields

  • id objectid

    Unique identifier for the category.

  • name string

    A human-friendly name for the category.

  • active bool, default: false

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

  • children link

    Expandable list of child categories.

  • date_created auto date

    Date and time the category was created.

  • date_updated auto date

    Date and time the category was last updated.

  • description string

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

  • images array

    List of images depicting the category.

    Show images fields
    • images.id objectid

      Unique identifier for the object.

    • images.caption string

      A brief description of the image.

    • images.file file

      An object representing the image file.

      Show file fields
      • images.file.id objectid

        Unique identifier for the file.

      • images.file.content_type string

        MIME content type of the file.

      • images.file.data filedata

        A reference to the raw file data.

      • images.file.date_uploaded date

        Date the file was uploaded.

      • images.file.filename string

        Optional file name.

      • images.file.height int

        Image height in pixels, if applicable.

      • images.file.length int

        Size of the file in bytes.

      • images.file.md5 string

        An MD5 hash of the file contents. This can be used to uniquely identify the file for caching purposes.

      • images.file.url string

        A public URL to reference the file. Updated automatically if file content changes.

      • images.file.width int

        Image width in pixels, if applicable.

  • meta_description string

    Page description used for search engine optimization purposes.

  • meta_keywords string

    Page keywords used for search engine optimization purposes.

  • meta_title string

    Page title used to override product name in storefronts.

  • parent_id objectid

    ID of the parent category, if applicable.

  • parent link

    Expandable link to the parent category, if applicable.

  • products_indexed link

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

  • products collection

    Expandable list of category products.

  • slug string

    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.

  • sort int

    Position of the category in a list.

  • sorting string

    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_id auto objectid

    ID of the top level category in the hierarchy.

  • top link

    Expandable link to the top level category.

Create a category

POST /categories

$ curl https://api.swell.store/categories \
  -u store-id:secret-key \
  -d name=Widgets \
  -d active=true \
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.post('/categories', {
  name: 'Widgets',
  active: true,
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->post('/categories', [
  'name' => 'Widgets',
  'active' => true
]);

Example response

{
  "id": "5ca9871f9b14d199072432a1",
  "active": false,
  "name": "Widgets",
  "slug": "widgets",
  "date_created": "2019-04-01T00:00:00.000Z"
}

Create a new category.

Arguments

  • name required

    A human-friendly name for the category.

  • active optional

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

  • description optional

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

  • slug optional

    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.

  • Show all arguments
    • images optional

      List of images depicting the category.

      Show images arguments
      • images.caption optional

        A brief description of the image.

      • images.file optional

        An object representing the image file.

        Show file arguments
        • images.file.data optional

          Set or overwrite file data. Use the following format when writing a file from binary data (for example an image): data[$binary]=<base64 encoded binary daya>.

        • images.file.filename optional

          Optional file name.

    • meta_description optional

      Page description used for search engine optimization purposes.

    • meta_keywords optional

      Page keywords used for search engine optimization purposes.

    • meta_title optional

      Page title used to override product name in storefronts.

    • parent_id optional

      ID of the parent category, if applicable.

    • sorting optional

      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.

    • sort optional

      Position of the category in a list.

Returns

Returns a new category if valid arguments are provided, otherwise returns an object containing validation errors.

Retrieve a category

GET /categories/:id

$ curl https://api.swell.store/categories/5ca9871f9b14d199072432a1 \
  -u store-id:secret-key
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/categories/{id}', {
  id: '5ca9871f9b14d199072432a1',
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->get('/categories/{id}', [
  'id' => '5ca9871f9b14d199072432a1',
]);

Example 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
}

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

Arguments

  • id required

    ID of the category to retrieve.

  • expand optional

    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.

  • fields optional

    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.

  • include optional

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

Returns

Returns a category if a valid ID was provided. Otherwise null.

Update a category

PUT /categories/:id

$ curl https://api.swell.store/categories/5ca9871f9b14d199072432a1 \
  -u store-id:secret-key \
  -d price=9.99 \
  -X PUT
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.put('/categories/{id}', {
  id: '5ca9871f9b14d199072432a1',
  description: 'A bunch of widgets',
  active: false
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->put('/categories/{id}', [
  'id' => '5ca9871f9b14d199072432a1',
  'description' => 'A bunch of widgets',
  'active' => false
]);

Example 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
}

Update an existing category 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

  • id required

    Unique identifier for the category.

  • active optional

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

  • description optional

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

  • name optional

    A human-friendly name for the category.

  • slug optional

    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.

  • Show all arguments
    • images optional

      List of images depicting the category.

      Show images arguments
      • images.caption optional

        A brief description of the image.

      • images.file optional

        An object representing the image file.

        Show file arguments
        • images.file.data optional

          Set or overwrite file data. Use the following format when writing a file from binary data (for example an image): data[$binary]=<base64 encoded binary daya>.

        • images.file.filename optional

          Optional file name.

    • meta_description optional

      Page description used for search engine optimization purposes.

    • meta_keywords optional

      Page keywords used for search engine optimization purposes.

    • meta_title optional

      Page title used to override product name in storefronts.

    • parent_id optional

      ID of the parent category, if applicable.

    • sorting optional

      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.

    • sort optional

      Position of the category in a list.

Returns

Returns the updated category if valid arguments are provided, otherwise returns an object containing validation errors.

List all categories

GET /categories

$ curl https://api.swell.store/categories?limit=25&page=1 \
  -u store-id:secret-key \
  -G
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/categories', {
  where: {
    active: true
  },
  limit: 25,
  page: 1
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->get('/categories', [
  'where' => [
    'active' => true
  ],
  'limit' => 25,
  'page' => 1
]);

Example response

{
  "count": 51,
  "results": [
    {
      "id": "5f626b0d91f0af999b000012",
      "name": "Example category",
      "active": true,
      "date_created": "2020-09-16T19:44:13.642Z",
      "date_updated": "2020-09-16T19:44:13.642Z",
      "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": "5f626b0d91f0af999b000013",
      "slug": "example-category",
      "sort": 3,
      "sorting": "price_desc",
      "top_id": "5f626b0d91f0af999b000014"
    },
    {...},
    {...}
  ],
  "page": 1,
  "pages": {
    "1": {
      "start": 1,
      "end": 25
    },
    "2": {
      "start": 26,
      "end": 50
    },
    "2": {
      "start": 51,
      "end": 51
    }
  }
}

Return a list of product categories.

Arguments

  • expand optional

    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.

  • fields optional

    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.

  • include optional

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

  • limit optional

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

  • page optional

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

  • search optional

    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.

  • sort optional

    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.

  • where optional

    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.

Returns

An object with an array of results containing up to the limit and matching filters specified. If no records are found given the page and limit arguments, the results array will be empty. This request should never throw an error.

Delete a category

DELETE /categories/:id

$ curl https://api.swell.store/categories/5ca9871f9b14d199072432a1 \
  -u store-id:secret-key \
  -X DELETE
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.delete('/categories/{id}', {
  id: '5ca9871f9b14d199072432a1',
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->delete('/categories/{id}', [
  'id' => '5ca9871f9b14d199072432a1',
]);

Example 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
}

Delete a category.

Arguments

  • id required

    ID of the category to delete.

Returns

Returns the original category if the operation was successful, or null if the category was not found.

Attributes

Product attributes are additional characteristics of a product that can be used in different ways. Attributes can be made visible in your detail page with the visible flag, or hidden from view. Visible attributes are typically used to display a list of specifications in 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

The attribute object

{
  "id": "material",
  "name": "Color",
  "date_created": "2020-09-16T19:44:13.587Z",
  "date_updated": "2020-09-16T19:44:13.587Z",
  "default": null,
  "required": false,
  "type": "text",
  "values": [
    "Red",
    "White",
    "Blue",
    "Green",
    "Yellow",
    "Black"
  ],
  "visible": true
}

Fields

  • id auto string

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

  • name string

    A human-friendly name for the attribute.

  • date_created auto date

    Date and time the attribute was created.

  • date_updated auto date

    Date and time the attribute was last updated.

  • default mixed

    Default value used when entering a value for the attribute.

  • multi bool

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

  • products link

    Expandable list of products using the attribute.

  • required bool, default: false

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

  • type string

    Input type used when entering a value for the attribute.

  • values array

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

  • visible bool, default: false

    Indicates the attribute is visible to customers.

Create an attribute

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
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.post('/attributes', {
  name: 'Material',
  visible: true,
  type: 'dropdown',
  values: [
    'Cotton',
    'Polyester',
    'Wool'
  ],
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->post('/attributes', [
  'name' => 'Material',
  'visible' => true,
  'type' => 'dropdown',
  'values' => [
    'Cotton',
    'Polyester',
    'Wool'
  ],
]);

Example response

{
  "id": "material",
  "name": "Material",
  "date_created": "2019-04-01T00:00:00.000Z",
  "required": false,
  "visible": true,
  "type": "dropdown",
  "values": [
    "Cotton",
    "Polyester",
    "Wool"
  ]
}

Create a new attribute.

Arguments

  • id required

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

  • name required

    A human-friendly name for the attribute.

  • required optional

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

  • type optional

    Input type used when entering a value for the attribute.

  • values optional

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

  • visible optional

    Set true to make the attribute visible to customers in a storefront.

  • Show all arguments
    • default optional

      Default value used when entering a value for the attribute.

    • multi optional

      When attribute type=image used, set true to allow multiple image uploads.

Returns

Returns a new attribute if valid arguments are provided, otherwise returns an object containing validation errors.

Retrieve an attribute

GET /attributes/:id

$ curl https://api.swell.store/attributes/material \
  -u store-id:secret-key
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/attributes/{id}', {
  id: 'material',
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->get('/attributes/{id}', [
  'id' => 'material',
]);

Example 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 existing attribute using the ID, that was returned when created.

Arguments

  • id required

    ID of the attribute to retrieve.

  • expand optional

    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.

  • fields optional

    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 attribute id is always returned.

  • include optional

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

Returns

Returns a attribute if a valid ID was provided. Otherwise null.

Update an attribute

PUT /attributes/:id

$ curl https://api.swell.store/attributes/material \
  -u store-id:secret-key \
  -d required=true \
  -X PUT
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.put('/attributes/{id}', {
  id: 'material',
  required: true
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->put('/attributes/{id}', [
  'id' => 'material',
  'required' => true
]);

Example 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"
  ]
}

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

  • id required

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

  • name optional

    A human-friendly name for the attribute.

  • required optional

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

  • type optional

    Input type used when entering a value for the attribute.

  • values optional

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

  • visible optional

    Set true to make the attribute visible to customers in a storefront.

  • Show all arguments
    • default optional

      Default value used when entering a value for the attribute.

    • multi optional

      When attribute type=image used, set true to allow multiple image uploads.

Returns

Returns the updated attribute if valid arguments are provided, otherwise returns an object containing validation errors.

List all attributes

GET /attributes

$ curl https://api.swell.store/attributes?limit=25&page=1 \
  -u store-id:secret-key \
  -G
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/attributes', {
  limit: 25,
  page: 1
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->get('/attributes', [
  'limit' => 25,
  'page' => 1
]);

Example response

{
  "count": 51,
  "results": [
    {
      "id": "material",
      "name": "Color",
      "date_created": "2020-09-16T19:44:13.587Z",
      "date_updated": "2020-09-16T19:44:13.587Z",
      "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
    }
  }
}

Return a list of product attributes.

Arguments

  • expand optional

    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.

  • fields optional

    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 attribute id is always returned.

  • include optional

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

  • limit optional

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

  • page optional

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

  • search optional

    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.

  • sort optional

    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.

  • where optional

    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.

Returns

An object with an array of results containing up to the limit and matching filters specified. If no records are found given the page and limit arguments, the results array will be empty. This request should never throw an error.

Delete an attribute

DELETE /attributes/:id

$ curl https://api.swell.store/attributes/material \
  -u store-id:secret-key \
  -X DELETE
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.delete('/attributes/{id}', {
  id: 'material',
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->delete('/attributes/{id}', [
  'id' => 'material',
]);

Example 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"
  ]
}

Delete an attribute.

Arguments

  • id required

    ID of the attribute to delete.

Returns

Returns the original attribute if the operation was successful, or null if the attribute was not found.

Orders

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

The cart object

{
  "id": "5f626b0d91f0af999b00000e",
  "abandoned": false,
  "account_id": "5f626b0d91f0af999b00000f",
  "account_info_saved": true,
  "account_logged_in": true,
  "billing": {
    "name": "Jon Snow",
    "first_name": "Jon",
    "last_name": "Snow",
    "address1": "1 Main Street",
    "city": "Brooklyn",
    "state": "NY",
    "zip": 11201,
    "country": "US",
    "phone": "(555) 555-5555",
    "method": "card",
    "card": {
      "token": "card_1Ds1K7E30PFlZWil6Q7bJ1PD",
      "test": true,
      "last4": "4242",
      "brand": "Visa",
      "address_check": "unchecked",
      "zip_check": "unchecked",
      "cvc_check": "unchecked",
      "exp_month": 1,
      "exp_year": 2029,
      "fingerprints": "3e63991847bbdaafdbc5c8f110ad803f"
    },
    "account_card_id": "5c3ac9870b3b171a7dfaf089"
  },
  "checkout_id": "e785b5ac4355ceef41ae2fd1c47df4bc",
  "comments": null,
  "coupon_code": "WINTERSALE",
  "coupon_id": "5f626b0d91f0af999b000010",
  "currency": "USD",
  "date_created": "2020-09-16T19:44:13.623Z",
  "date_updated": "2020-09-16T19:44:13.623Z",
  "date_webhook_first_failed": null,
  "discount_total": 5,
  "discounts": [
    {
      "id": "coupon-0",
      "type": "coupon",
      "amount": 5,
      "rule": {
        "type": "product",
        "value_type": "fixed",
        "value_amount": 2.5,
        "product_id": "5c524166f4e8f3446a10331b"
      }
    }
  ],
  "gift_message": null,
  "gift": true,
  "giftcard_total": 25,
  "giftcards": [
    {
      "id": "5841c5691c64c63e75d29e43",
      "amount": 25,
      "code": "B6UQY3DHRCM4BQYU",
      "code_formatted": "B6UQ Y3DH RCM4 BQYU",
      "last4": "BQYU"
    }
  ],
  "grand_total": 41.98,
  "guest": false,
  "item_discount": 5,
  "item_quantity": 2,
  "item_shipment_weight": 2,
  "item_tax": 2,
  "items": [
    {
      "id": "5ca537326a0ec32a521139dd",
      "product_id": "5c524166f4e8f3446a10331b",
      "variant_id": "5c524166f4e8f3446a10331f",
      "quantity": 2,
      "price": 19.99,
      "price_total": 38.98,
      "orig_price": 19.99,
      "delivery": "shipment",
      "shipment_weight": 1,
      "options": [
        {
          "id": "5becb84fac207653a4816ee5",
          "name": "Size",
          "value": "Small",
          "variant": true
        },
        {
          "id": "5becb84fac207653a4816ee6",
          "name": "Color",
          "value": "Yellow",
          "variant": true
        }
      ],
      "discounts": [
        {
          "id": "coupon-0",
          "amount": 5
        }
      ],
      "discount_each": 2.5,
      "discount_total": 5,
      "taxes": [
        {
          "id": "sales-tax",
          "amount": 2
        }
      ],
      "tax_each": 1,
      "tax_total": 2
    }
  ],
  "notes": null,
  "number": 2039476,
  "order_id": "5f626b0d91f0af999b000011",
  "promotion_ids": null,
  "shipment_delivery": true,
  "shipment_discount": 0,
  "shipment_price": 5,
  "shipment_rating": {
    "fingerprint": "71e03117e684192f4f33569dab1c74ee",
    "services": [
      {
        "id": "standard",
        "name": "Standard Shipping",
        "price": 5
      },
      {
        "id": "express",
        "name": "Express Shipping",
        "price": 10
      },
      {
        "id": "next_day",
        "name": "Next Day Shipping",
        "price": 20
      }
    ],
    "errors": null
  },
  "shipment_tax": 0,
  "shipment_tax_included_total": 5,
  "shipment_total": 5,
  "shipping": {
    "name": "Jon Snow",
    "first_name": "Jon",
    "last_name": "Snow",
    "address1": "1 Main Street",
    "city": "Brooklyn",
    "state": "NY",
    "zip": 11201,
    "country": "US",
    "phone": "(555) 555-5555",
    "price": 5,
    "service": "standard",
    "service_name": "Standard",
    "account_address_id": "5c12c5fdfcd74b34e19cf659"
  },
  "status": "converted",
  "sub_total": 38.98,
  "tax_included_total": 2,
  "tax_total": 2,
  "taxes": [
    {
      "id": "sales-tax",
      "name": "Sales tax",
      "priority": 1,
      "rate": 0.1,
      "amount": 2
    }
  ],
  "webhook_attempts_failed": null,
  "webhook_response": null,
  "webhook_status": 200
}

Fields

  • id objectid

    Unique identifier for the cart.

  • abandoned auto bool

    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_notifications auto int

    Number of abandoned cart notifications sent to the customer.

  • account link

    Expandable link to the customer's account.

  • account_credit_amount currency

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

  • account_id objectid

    ID of the customer's account.

  • account_info_saved bool

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

  • account_logged_in bool

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

  • active auto bool

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

  • billing object

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

    Show billing fields
    • billing.account_card_id objectid

      ID of the customer's credit card on file, if applicable.

    • billing.account_card link

      Expandable link to the customer's credit card on file, if applicable.

    • billing.address1 string

      Billing address line 1 (street address/PO box/company name).

    • billing.address2 string

      Billing address line 2 (apartment/suite/unit/building).

    • billing.amazon object

      Amazon billing details used when billing.method=amazon.

      Show amazon fields
      • billing.amazon.access_token string

        Amazon access token provided when a customer authorizes payment in a storefront.

      • billing.amazon.order_reference_id string

        Amazon order reference ID created when a customer initiates payment in a storefront.

    • billing.card object

      Credit card billing details used when billing.method=card.

      Show card fields
      • billing.card.token string

        Token generated by Swell Checkout or Stripe.js.

      • billing.card.address_check string

        When used with a payment gateway that performs address checks and address1 was provided, can be pass, fail, unavailable or unchecked.

      • billing.card.brand string

        Credit card brand. Can be American Express, Diners Club, Discover, JCB, MasterCard, UnionPay, Visa, or Unknown.

      • billing.card.cvc_check string

        When used with a payment gateway that performs CVC code checks and cvc was provided, can be pass, fail, unavailable or unchecked.

      • billing.card.exp_month int

        Two-digit number representing the credit card expiration month.

      • billing.card.exp_year int

        Four-digit number representing the credit card expiration year.

      • billing.card.last4 string

        Last four digits of the card number.

      • billing.card.zip_check string

        When used with a payment gateway that performs address checks and zip was provided, can be pass, fail, unavailable or unchecked.

    • billing.city string

      Billing city/district/suberb/town/village.

    • billing.country string

      Two-letter ISO code country code.

    • billing.default bool

      Indicates billing details represent the customer's default payment method.

    • billing.first_name string

      Billing first name. If name is updated, then first_name will be automatically updated as the first word of the name.

    • billing.last_name string

      Billing last name. If name is updated, then last_name will be automatically updated as the last words of the name.

    • billing.method string

      Method of payment. Can be card, account, amazon, paypal or any one of the manual methods defined in payment settings.

    • billing.name string

      Billing full name. If first_name or last_name are updated, then name will be automatically updated as a combination of first/last.

    • billing.paypal object

      PayPal billing details used when billing.method=paypal.

      Show paypal fields
      • billing.paypal.payer_id string

        PayPal payer ID provided when a customer authorizes payment in a storefront.

      • billing.paypal.payment_id string

        PayPal payment ID created when a customer initiates payment in a storefront.

    • billing.phone string

      Billing phone number.

    • billing.state string

      Billing state/county/province/region.

    • billing.zip string

      Billing zip/postal code.

  • checkout_id auto objectid

    Customer-facing unique identifier for the cart used in URLs and for abandoned cart recovery.

  • comments string

    Customer notes provided when placing the order, if any.

  • coupon_code string

    Coupon code applied to the cart. See coupons for details.

  • coupon_id objectid

    ID of the coupon applied to the cart.

  • coupon link

    Expandable link to the coupon applied to the cart.

  • currency auto string

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

  • date_abandoned_next date

    Next date the cart will be marked as abandoned when using a series of abandoned cart recovery notices (a.k.a Advanced Cart Recovery).

  • date_abandoned date

    Date the cart was or will be marked as abandoned.

  • date_created auto date

    Date and time the cart was created.

  • date_updated auto date

    Date and time the cart was last updated.

  • date_webhook_first_failed auto date

    Date the order webhook first failed, if applicable. Value is unset after an order webhook is successfully returned for the record.

  • discount_total auto currency

    Total discount amount.

  • discounts array

    List of discounts applied to the cart.

    Show discounts fields
    • discounts.id string

      Unique identifier for the object.

    • discounts.amount currency

      Fixed discount amount.

    • discounts.rule object

      Object describing the discount rule details. Custom discounts don't require this value.

    • discounts.type string

      Type of discount. Can be coupon or promo-<id> referring to the source of the discount. Custom discounts don't require this value.

  • gift_message string

    Optional message to include with the order when shipping to the recipient.

  • gift bool

    Indicates the order is intended as a gift for the recipient.

  • giftcard_delivery bool

    Indicates the cart has at least one line item with delivery=giftcard.

  • giftcard_total auto currency

    Total payment amount applied to the order from giftcards.

  • giftcards array

    List of gift cards applied to the cart.

    Show giftcards fields
    • giftcards.id objectid

      Unique identifier for the object.

    • giftcards.amount currency

      Amount of the gift card balance to spend for initial payment. If not specified, each gift cards will be spent in order until payment is completed.

    • giftcards.code_formatted string

      Fully formatted gift card code for display purposes.

    • giftcards.code string

      Gift card code to apply. A validation error will be returned if the code is not valid.

    • giftcards.giftcard link

      Expandable link to the gift card record.

    • giftcards.last4 string

      Last four digits of the gift card code.

  • grand_total auto currency

    Grand total including items, shipping and taxes.

  • guest bool

    Indicates the customer was not logged in when placing the order.

  • item_discount auto currency

    Total discount applied to line items.

  • item_quantity auto int

    Total quantity of all line items.

  • item_shipment_weight auto float

    Total shipping weight of all line items.

  • item_tax auto currency

    Total taxes applied to line items.

  • item_tax_included bool

    Indicates line item prices include taxes.

  • items array

    List of line items describing the products ordered.

    Show items fields
    • items.id objectid

      Unique identifier for the item.

    • items.bundle_items array

      List of items offered as a bundle. Defaults to product.bundle_items.

      Show bundle_items fields
      • items.bundle_items.id objectid

        Unique identifier for the object.

      • items.bundle_items.product_id objectid

        ID of the bundle item product.

      • items.bundle_items.delivery string

        Method of delivery taken automatically from product.delivery.

      • items.bundle_items.product link

        Expandable link to the bundle item product.

      • items.bundle_items.quantity_total int

        Total quantity of the bundle item to be fulfilled, calculated as item.quantity * bundle_item.quantity.

      • items.bundle_items.quantity int

        Quantity of the bundle item being ordered. Defaults to 1.

      • items.bundle_items.shipment_weight float

        Shipping weight taken automatically from product.shipment_weight, if applicable.

      • items.bundle_items.variant link

        Expandable link to the bundle item variant.

      • items.bundle_items.variant_id objectid

        ID of the bundle item variant.

    • items.delivery string

      Method of delivery taken automatically from product.delivery.

    • items.description string

      Description used for custom line items, when product is not defined.

    • items.discount_each currency

      Total discount amount divided by quantity.

    • items.discount_total currency

      Total discount applied to the item.

    • items.discounts array

      List of discounts applied to the item by coupons, promotions or custom logic.

      Show discounts fields
      • items.discounts.id string

        Unique identifier for the object. Refers to one of the IDs in the cart discounts object.

      • items.discounts.amount currency

        Fixed discount amount.

    • items.options array

      Item options matching one or more of product.options. When adding to the cart, specify either option id or name (case-insensitive) to identify the option.

      Gift card products have two special options that can be used when fulfilling gift cards by email. Use the option ID send_email and value as the recipient email address, and send_note as a custom message from the customer to the receipient sent by email.

      Show options fields
      • items.options.id string

        Unique identifier for the object.

      • items.options.name string

        Name of the product option. Populated automatically when adding an option by ID.

      • items.options.price currency

        Additional price added onto the base price of the product.

      • items.options.shipment_weight float

        Additional shipping weight added onto the base weight of the product.

      • items.options.subscription bool

        Indicates the option refers to a subscription plan interval.

      • items.options.value string

        Name value of the product option. When adding to the cart, specify either the product option value id or name (case-insensitive) to identify the value.

      • items.options.variant bool

        Indicates the option refers to a variant aspect.

    • items.orig_price currency

      Original item price used internally to determine if the item price was overridden and should be automatically updated when item options are changed.

    • items.price currency

      Price of the item. If a product price is reduced by a sale or price rule, this would be set to the reduced price automatically. Also, item price can be overridden when adding to a cart. Line item prices don't change unless explicitly edited by a store admin.

    • items.price_total currency

      Total price added to sub total by multiplying quantity and price.

    • items.product_id objectid

      ID of the item product.

    • items.product link

      Expandable link to the item product.

    • items.quantity int

      Quantity of the item being ordered. Defaults to 1.

    • items.shipment_weight float

      Shipping weight taken automatically from product.shipment_weight, if applicable.

    • items.subscription_interval string

      Refers to the subscription interval that applies when delivery=subscription.

    • items.subscription_interval_count int

      Refers to the subscription interval count that applies when delivery=subscription.

    • items.subscription_trial_days int

      Refers to the subscription trial period that applies when delivery=subscription.

    • items.tax_each currency

      Total tax amount divided by quantity.

    • items.tax_total currency

      Total tax applied to the item.

    • items.taxes array

      List of tax rules applied to the item based on tax settings or custom logic.

      Show taxes fields
      • items.taxes.id string

        Unique identifier for the object. Refers to one of the IDs in the cart taxes object.

      • items.taxes.amount currency

        Fixed tax amount.

    • items.variant link

      Expandable link to the item variant, if applicable.

    • items.variant_id objectid

      ID of the item variant, if applicable.

  • notes string

    Internal admin notes. These are not visible to the customer.

  • number auto string

    Unique incremental cart number, assigned automatically using a format configured in general settings.

  • order_id auto objectid

    ID of the the converted order, if applicable.

  • order link

    Expandable link to the converted order, if applicable.

  • promotion_ids array

    List of promotion IDs applied to the cart.

  • promotions link

    Expandable list of promotions applied to the cart.

  • recovered bool

    Indicates the cart was recovered and converted to an order after being abandoned.

  • shipment_delivery bool

    Indicates the cart has at least one line item with delivery=shipment.

  • shipment_discount currency

    Shipping discount applied by coupons, promotions or custom logic.

  • shipment_price auto currency

    Total shipping price before discounts.

  • shipment_rating auto object

    Object describing the shipping services and rates available for the cart. Shipping country must be set before retrieving shipping rates.

    Show shipment_rating fields
    • shipment_rating.date_created date

      Date and time the object was created.

    • shipment_rating.errors array

      List of errors generated while retrieving rates, if any. When using 3rd party shipping services, any system errors will be listed here.

      Show errors fields
      • shipment_rating.errors.code string

        Unique code describing the error.

      • shipment_rating.errors.message string

        Message describing the error.

    • shipment_rating.fingerprint string

      Unique fingerprint identifying the parameters used to calculate shipping rates. Rates should always be the same given the same parameters and shipping settings.

    • shipment_rating.services array

      List of shipping services and rates available.

      Show services fields
      • shipment_rating.services.id string

        Unique identifier for the object.

      • shipment_rating.services.carrier string

        Name of a 3rd party carrier offering the service, if applicable.

      • shipment_rating.services.name string

        Name of the shipping service.

      • shipment_rating.services.price currency

        Price of the shipping service.

  • shipment_tax currency

    Shipping tax amount, if applicable.

  • shipment_tax_included_total auto currency

    Total of taxes applied separately from line items.

  • shipment_tax_included bool

    Indicates shipping total includes taxes, if applicable.

  • shipment_total auto currency

    Total shipping price after discounts.

  • shipping object

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

    Show shipping fields
    • shipping.account_address_id objectid

      ID of the customer's address on file.

    • shipping.account_address link

      Expandable link to the customer's address on file.

    • shipping.address1 string

      Shipping address line 1 (street address/PO box/company name).

    • shipping.address2 string

      Shipping address line 2 (apartment/suite/unit/building).

    • shipping.city string

      Shipping city/district/suberb/town/village.

    • shipping.country string

      Two-letter ISO code country code.

    • shipping.default bool

      Indicates shipping details represent the customer's default shipping address.

    • shipping.first_name string

      Shipping first name. If name is updated, then first_name will be automatically updated as the first word of the name.

    • shipping.last_name string

      Shipping last name. If name is updated, then last_name will be automatically updated as the last words of the name.

    • shipping.name string

      Shipping full name. If first_name or last_name are updated, then name will be automatically updated as a combination of first/last.

    • shipping.phone string

      Shipping phone number.

    • shipping.price currency

      Price of the shipping service. Defaults to shipment_rating.services.price chosen by setting service.

    • shipping.service_name string

      Name of the shipping service. Defaults to shipment_rating.services.name chosen by setting service.

    • shipping.service string

      ID of a shipping service as configured in shipment settings. Normally, this would be applied after retrieving shipping rates by using one of the shipment_rating.services.id values.

    • shipping.state string

      Shipping state/county/province/region.

    • shipping.zip string

      Shipping zip/postal code.

  • status auto string, default: active

    Current status of the cart. Can be active, converted, abandoned or recovered.

  • sub_total auto currency

    Sum of all line items before discounts, taxes and shipping.

  • subscription_delivery bool

    Indicates the cart has at least one line item with delivery=subscription.

  • tax_included_total auto currency

    Total with shipping and item taxes included. Allows for an alternate display style, as normally sub_total and tax_total are shown separately.

  • tax_total auto currency

    Total tax amount applied to the cart including line items and shipping.

  • taxes array

    List of taxes applied to the cart.

    Show taxes fields
    • taxes.id string

      Unique identifier for the object.

    • taxes.amount currency

      Fixed tax amount.

    • taxes.name string

      Name of the tax rule, for example "NY Sales Tax".

    • taxes.priority int

      Priority indicates the order in which a tax rule was applied. Higher priority rules are added on top of other tax rules with a lower priority. Rules with the same priority are calculated excluding each other.

    • taxes.rate float

      Tax percentage used in calculating the fixed amount.

    • taxes.shipping bool

      Indicates the tax applies to shipping.

  • webhook_attempts_failed auto int

    Number of failed order webhook attempts, if applicable. Value is unset after an order webhook is successfully returned for the record.

  • webhook_response auto string

    Text response of the last failed order webhook attempt, if applicable. Value is unset after an order webhook is successfully returned for the record.

  • webhook_status auto int

    HTTP response status of the last failed order webhook attempt, if applicable. Value is unset after an order webhook is successfully returned for the record.

Create a cart

POST /carts

$ curl https://api.swell.store/carts \
  -u store-id:secret-key \
  -d items[0][product_id]=5cad15bc9b14d1990724663a \
  -d items[0][quantity]=2 \
  -d coupon_code=FREESHIPPING
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.post('/carts', {
  items: [
    {
      product_id: '5cad15bc9b14d1990724663a',
      quantity: 2,
    }
  ],
  billing: {
    ...
  },
  shipping: {
    ...
  },
  coupon_code: 'FREESHIPPING',
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->post('/carts', [
  'items' => [
    [
      'product_id' => '5cad15bc9b14d1990724663a',
      'quantity' => 2,
    ]
  ],
  'billing' => [
    ...
  ],
  'shipping' => [
    ...
  ],
  'coupon_code' => 'FREESHIPPING',
]);

Example response

{
  "id": "5cad15bc9b14d1990724663a",
  "active": true,
  "billing": {...},
  "shipping": {...},
  "items": [
    {
      "id": "5a9ea7ba3f95740a914267f2",
      "product_id": "5cad15bc9b14d1990724663b",
      "quantity": 2,
      "price": 9.99,
      "price_total": 18.98,
      "shipment_weight": 1.5,
      ...
    }
  ],
  "coupon_code": "FREESHIPPING",
  "currency": "USD",
  "date_created": "2019-04-01T00:00:00.000Z",
  "discount_total": 0,
  "grand_total": 18.98,
  "item_quantity": 2,
  "item_shipment_weight": 3.0,
  "item_tax": 0,
  "number": "100101",
  "shipment_price": 0,
  "shipment_total": 0,
  "status": "active",
  "sub_total": 0,
  "tax_total": 0,
  ...
}

Create a new cart.

Arguments

  • account_id optional

    ID of the customer's account.

  • billing optional

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

    Show billing arguments
    • billing.account_card_id optional

      Setting this value will populate billing.card with the associated customer's credit card on file.

    • billing.address1 optional

      Billing address line 1 (street address/PO box/company name).

    • billing.address2 optional

      Billing address line 2 (apartment/suite/unit/building).

    • billing.amazon optional

      Amazon billing details used when billing.method=amazon.

      Show amazon arguments
      • billing.amazon.access_token optional

        Amazon access token provided when a customer authorizes payment in a storefront.

      • billing.amazon.order_reference_id optional

        Amazon order reference ID created when a customer initiates payment in a storefront.

    • billing.card optional

      Credit card billing details used when billing.method=card.

      Show card arguments
      • billing.card.token required

        Token generated by Swell Checkout or Stripe.js.

      • billing.card.brand optional

        Credit card brand. Can be American Express, Diners Club, Discover, JCB, MasterCard, UnionPay, Visa, or Unknown.

      • billing.card.exp_month optional

        Two-digit number representing the credit card expiration month.

      • billing.card.exp_year optional

        Four-digit number representing the credit card expiration year.

      • billing.card.last4 optional

        Last four digits of the card number.

    • billing.city optional

      Billing city/district/suberb/town/village.

    • billing.country optional

      Two-letter ISO code country code.

    • billing.first_name optional

      Billing first name. If name is updated, then first_name will be automatically updated as the first word of the name.

    • billing.last_name optional

      Billing last name. If name is updated, then last_name will be automatically updated as the last words of the name.

    • billing.method optional

      Method of payment. Can be card, account, amazon, paypal or any one of the manual methods defined in payment settings.

    • billing.name optional

      Billing full name. If first_name or last_name are updated, then name will be automatically updated as a combination of first/last.

    • billing.paypal optional

      PayPal billing details used when billing.method=paypal.

      Show paypal arguments
      • billing.paypal.payer_id optional

        PayPal payer ID provided when a customer authorizes payment in a storefront.

      • billing.paypal.payment_id optional

        PayPal payment ID created when a customer initiates payment in a storefront.

    • billing.phone optional

      Billing phone number.

    • billing.state optional

      Billing state/county/province/region.

    • billing.zip optional

      Billing zip/postal code.

  • coupon_code optional

    Set a valid coupon code to apply the coupon's discount. If the code is not found or invalid, a validation error is returned.

  • items optional

    List of line items describing the products ordered.

    Show items arguments
    • items.bundle_items optional

      List of items offered as a bundle. Defaults to product.bundle_items.

      Show bundle_items arguments
      • items.bundle_items.product_id required

        ID of the bundle item product.

      • items.bundle_items.quantity optional

        Quantity of the bundle item being ordered. Defaults to 1.

      • items.bundle_items.shipment_weight optional

        Weight to be used in shipping calculation, if applicable.

      • items.bundle_items.variant_id optional

        ID of the bundle item variant.

    • items.description optional

      Description used for custom line items, when product is not defined.

    • items.discounts optional

      List of discounts to apply to the item. Normally populated by applying a coupon or promotions.

      Show discounts arguments
      • items.discounts.id required

        Unique identifier for the object. Should refer to one of the IDs in the cart discounts object.

      • items.discounts.amount required

        Fixed discount amount.

    • items.options optional

      Item options matching one or more of product.options. When adding to the cart, specify either option id or name (case-insensitive) to identify the option.

      Gift card products have two special options that can be used when fulfilling gift cards by email. Use the option ID send_email and value as the recipient email address, and send_note as a custom message from the customer to the receipient sent by email.

      Show options arguments
      • items.options.id optional

        Unique identifier for the object.

      • items.options.name optional

        Name of the product option. Populated automatically when adding an option by ID.

      • items.options.price optional

        Additional price added onto the base price of the product.

      • items.options.shipment_weight optional

        Additional shipping weight added onto the base weight of the product.

      • items.options.subscription optional

        Indicates the option refers to a subscription plan interval.

      • items.options.value optional

        Name value of the product option. When adding to the cart, specify either the product option value id or name (case-insensitive) to identify the value.

      • items.options.variant optional

        Indicates the option refers to a variant aspect.

    • items.price optional

      Price of the item. Override this value to set a custom price. Defaults to product price or sale price.

    • items.product_id optional

      ID of the item product.

    • items.quantity optional

      Quantity of the item being ordered. Defaults to 1.

    • items.shipment_weight optional

      Weight to be used in shipping calculation, if applicable.

    • items.taxes optional

      List of tax rules to apply to the item. Normally populated by tax settings.

      Show taxes arguments
      • items.taxes.id required

        Unique identifier for the object. Should refer to one of the IDs in the cart taxes object.

      • items.taxes.amount required

        Fixed tax amount.

    • items.variant_id optional

      ID of the item variant, if applicable.

  • shipping optional

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

    Show shipping arguments
    • shipping.account_address_id optional

      Setting this value will populate shipping with the associated customer's account address on file.

    • shipping.address1 optional

      Shipping address line 1 (street address/PO box/company name).

    • shipping.address2 optional

      Shipping address line 2 (apartment/suite/unit/building).

    • shipping.city optional

      Shipping city/district/suberb/town/village.

    • shipping.country optional

      Two-letter ISO code country code.

    • shipping.default optional

      Indicates shipping details represent the customer's default shipping address.

    • shipping.first_name optional

      Shipping first name. If name is updated, then first_name will be automatically updated as the first word of the name.

    • shipping.last_name optional

      Shipping last name. If name is updated, then last_name will be automatically updated as the last words of the name.

    • shipping.name optional

      Shipping full name. If first_name or last_name are updated, then name will be automatically updated as a combination of first/last.

    • shipping.phone optional

      Shipping phone number.

    • shipping.price optional

      Price of the shipping service. Defaults to shipment_rating.services.price chosen by setting service.

    • shipping.service optional

      ID of a shipping service as configured in shipment settings. Normally, this would be applied after retrieving shipping rates by using one of the shipment_rating.services.id values.

    • shipping.state optional

      Shipping state/county/province/region.

    • shipping.zip optional

      Shipping zip/postal code.

  • Show all arguments
    • account_credit_amount optional

      When applying gift cards to a cart, optionally indicate the total amount to spend from all gift cards applied. Defaults to the maximum amount available up to grand_total. Specifying an amount greater than the total available will return a validation error.

    • account_info_saved optional

      Set true when the customer has indicated they want to save shipping and billing information to their account for future use.

    • account_logged_in optional

      Set true when the customer has logged in with a password before submitting the order. This affects whether the order is considered as a guest checkout.

    • comments optional

      Customer notes provided when placing the order, if any.

    • coupon_id optional

      ID of the coupon applied to the cart.

    • date_abandoned optional

      Date the cart was or will be marked as abandoned.

    • date_abandoned_next optional

      Next date the cart will be marked as abandoned when using a series of abandoned cart recovery notices (a.k.a Advanced Cart Recovery).

    • discounts optional

      List of discounts to apply to the cart.

      Show discounts arguments
      • discounts.id optional

        Unique identifier for the object.

      • discounts.amount optional

        Fixed discount amount.

      • discounts.rule optional

        Object describing the discount rule details. Custom discounts don't require this value.

      • discounts.type optional

        Type of discount. Can be coupon or promo-<id> referring to the source of the discount. Custom discounts don't require this value.

    • gift_message optional

      Optional message to include with the order when shipping to the recipient.

    • giftcards optional

      List of gift cards to apply to the cart.

      Show giftcards arguments
      • giftcards.amount optional

        Amount of the gift card balance to spend on this order. Defaults to giftcard.balance.

      • giftcards.code optional

        Specify a gift card code to apply to the cart. If the code is not found or invalid, a validation error is returned. Case-insensitive.

    • gift optional

      Set true when the order is indented as a gift for the recipient.

    • guest optional

      Set true when the cart is a guest checkout. Defaults to not(account_logged_in).

    • item_tax_included optional

      Indicates line item prices include taxes.

    • notes optional

      Internal admin notes. These are not visible to the customer.

    • promotion_ids optional

      Set a list of promotion IDs to apply to the cart, or null to clear all promotions.

    • recovered optional

      Set true to indicate the cart was recovered and converted to an order after being abandoned.

    • shipment_discount optional

      Shipping discount applied by coupons, promotions or custom logic.

    • shipment_tax_included optional

      Indicates shipping total includes taxes, if applicable.

    • shipment_tax optional

      Shipping tax amount, if applicable.

    • taxes optional

      List of taxes to apply to the cart.

      Show taxes arguments
      • taxes.id optional

        Unique identifier for the object.

      • taxes.amount optional

        Fixed tax amount.

      • taxes.name optional

        Name of the tax rule, for example "NY Sales Tax".

      • taxes.rate optional

        Tax percentage used in calculating the fixed amount.

      • taxes.shipping optional

        Indicates the tax applies to shipping.

Returns

Returns a new cart if valid arguments are provided, otherwise returns an object containing validation errors.

Retrieve a cart

GET /carts/:id

$ curl https://api.swell.store/carts/5cad15bc9b14d1990724663a \
  -u store-id:secret-key
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/carts/{id}', {
  id: '5cad15bc9b14d1990724663a',
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->get('/carts/{id}', [
  'id' => '5cad15bc9b14d1990724663a',
]);

Example response

{
  "id": "5cad15bc9b14d1990724663a",
  "active": true,
  "billing": {...},
  "shipping": {...},
  "items": [
    {
      "id": "5a9ea7ba3f95740a914267f2",
      "product_id": "5cad15bc9b14d1990724663b",
      "quantity": 2,
      "price": 9.99,
      "price_total": 18.98,
      "shipment_weight": 1.5,
      ...
    }
  ],
  "coupon_code": "FREESHIPPING",
  "currency": "USD",
  "date_created": "2019-04-01T00:00:00.000Z",
  "discount_total": 0,
  "grand_total": 18.98,
  "item_quantity": 2,
  "item_shipment_weight": 3.0,
  "item_tax": 0,
  "number": "100101",
  "shipment_price": 0,
  "shipment_total": 0,
  "status": "active",
  "sub_total": 0,
  "tax_total": 0,
  ...
}

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

Arguments

  • id required

    ID of the cart to retrieve.

  • expand optional

    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.

  • fields optional

    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 cart id is always returned.

  • include optional

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

Returns

Returns a cart if a valid ID was provided. Otherwise null.

Update a cart

PUT /carts/:id

$ curl https://api.swell.store/carts/5cad15bc9b14d1990724663a \
  -u store-id:secret-key \
  -d name="Jon Snow" \
  -d address1="1 Main Street" \
  -d city=Brooklyn \
  -d state=NY \
  -d zip=11201 \
  -d country=US \
  -d phone="(555) 555-5555" \
  -X PUT
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.put('/carts/{id}', {
  id: '5cad15bc9b14d1990724663a',
  shipping: {
    name: 'Jon Snow',
    address1: '1 Main Street',
    city: 'Brooklyn',
    state: 'NY',
    zip: '11201',
    country: 'US',
    phone: '(555) 555-5555',
  },
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->put('/carts/{id}', [
  'id' => '5cad15bc9b14d1990724663a',
  'shipping' => [
    'name' => 'Jon Snow',
    'address1' => '1 Main Street',
    'city' => 'Brooklyn',
    'state' => 'NY',
    'zip' => '11201',
    'country' => 'US',
    'phone' => '(555) 555-5555'
  ]
]);

Example response

{
  "id": "5cad15bc9b14d1990724663a",
  "active": true,
  "billing": {...},
  "shipping": {
    "name": "Jon Snow",
    "first_name": "Jon",
    "last_name": "Snow",
    "address1": "1 Main Street",
    "city": "Brooklyn",
    "state": "NY",
    "zip": "11201",
    "country": "US",
    "phone": "(555) 555-5555"
  },
  "items": [
    {
      "id": "5a9ea7ba3f95740a914267f2",
      "product_id": "5cad15bc9b14d1990724663b",
      "quantity": 2,
      "price": 9.99,
      "price_total": 18.98,
      "shipment_weight": 1.5,
      ...
    }
  ],
  "coupon_code": "FREESHIPPING",
  "currency": "USD",
  "date_created": "2019-04-01T00:00:00.000Z",
  "date_updated": "2019-04-01T00:00:00.000Z",
  "discount_total": 0,
  "grand_total": 18.98,
  "item_quantity": 2,
  "item_shipment_weight": 3.0,
  "item_tax": 0,
  "number": "100101",
  "shipment_price": 0,
  "shipment_total": 0,
  "status": "active",
  "sub_total": 0,
  "tax_total": 0,
  ...
}

Update an existing cart 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

  • id required

    Unique identifier for the cart.

  • account_id optional

    ID of the customer's account.

  • billing optional

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

    Show billing arguments
    • billing.account_card_id optional

      Setting this value will populate billing.card with the associated customer's credit card on file.

    • billing.address1 optional

      Billing address line 1 (street address/PO box/company name).

    • billing.address2 optional

      Billing address line 2 (apartment/suite/unit/building).

    • billing.amazon optional

      Amazon billing details used when billing.method=amazon.

      Show amazon arguments
      • billing.amazon.access_token optional

        Amazon access token provided when a customer authorizes payment in a storefront.

      • billing.amazon.order_reference_id optional

        Amazon order reference ID created when a customer initiates payment in a storefront.

    • billing.card optional

      Credit card billing details used when billing.method=card.

      Show card arguments
      • billing.card.token required

        Token generated by Swell Checkout or Stripe.js.

      • billing.card.brand optional

        Credit card brand. Can be American Express, Diners Club, Discover, JCB, MasterCard, UnionPay, Visa, or Unknown.

      • billing.card.exp_month optional

        Two-digit number representing the credit card expiration month.

      • billing.card.exp_year optional

        Four-digit number representing the credit card expiration year.

      • billing.card.last4 optional

        Last four digits of the card number.

    • billing.city optional

      Billing city/district/suberb/town/village.

    • billing.country optional

      Two-letter ISO code country code.

    • billing.first_name optional

      Billing first name. If name is updated, then first_name will be automatically updated as the first word of the name.

    • billing.last_name optional

      Billing last name. If name is updated, then last_name will be automatically updated as the last words of the name.

    • billing.method optional

      Method of payment. Can be card, account, amazon, paypal or any one of the manual methods defined in payment settings.

    • billing.name optional

      Billing full name. If first_name or last_name are updated, then name will be automatically updated as a combination of first/last.

    • billing.paypal optional

      PayPal billing details used when billing.method=paypal.

      Show paypal arguments
      • billing.paypal.payer_id optional

        PayPal payer ID provided when a customer authorizes payment in a storefront.

      • billing.paypal.payment_id optional

        PayPal payment ID created when a customer initiates payment in a storefront.

    • billing.phone optional

      Billing phone number.

    • billing.state optional

      Billing state/county/province/region.

    • billing.zip optional

      Billing zip/postal code.

  • coupon_code optional

    Set a valid coupon code to apply the coupon's discount. If the code is not found or invalid, a validation error is returned.

  • items optional

    List of line items describing the products ordered.

    Show items arguments
    • items.bundle_items optional

      List of items offered as a bundle. Defaults to product.bundle_items.

      Show bundle_items arguments
      • items.bundle_items.product_id required

        ID of the bundle item product.

      • items.bundle_items.quantity optional

        Quantity of the bundle item being ordered. Defaults to 1.

      • items.bundle_items.shipment_weight optional

        Weight to be used in shipping calculation, if applicable.

      • items.bundle_items.variant_id optional

        ID of the bundle item variant.

    • items.description optional

      Description used for custom line items, when product is not defined.

    • items.discounts optional

      List of discounts to apply to the item. Normally populated by applying a coupon or promotions.

      Show discounts arguments
      • items.discounts.id required

        Unique identifier for the object. Should refer to one of the IDs in the cart discounts object.

      • items.discounts.amount required

        Fixed discount amount.

    • items.options optional

      Item options matching one or more of product.options. When adding to the cart, specify either option id or name (case-insensitive) to identify the option.

      Gift card products have two special options that can be used when fulfilling gift cards by email. Use the option ID send_email and value as the recipient email address, and send_note as a custom message from the customer to the receipient sent by email.

      Show options arguments
      • items.options.id optional

        Unique identifier for the object.

      • items.options.name optional

        Name of the product option. Populated automatically when adding an option by ID.

      • items.options.price optional

        Additional price added onto the base price of the product.

      • items.options.shipment_weight optional

        Additional shipping weight added onto the base weight of the product.

      • items.options.subscription optional

        Indicates the option refers to a subscription plan interval.

      • items.options.value optional

        Name value of the product option. When adding to the cart, specify either the product option value id or name (case-insensitive) to identify the value.

      • items.options.variant optional

        Indicates the option refers to a variant aspect.

    • items.price optional

      Price of the item. Override this value to set a custom price. Defaults to product price or sale price.

    • items.product_id optional

      ID of the item product.

    • items.quantity optional

      Quantity of the item being ordered. Defaults to 1.

    • items.shipment_weight optional

      Weight to be used in shipping calculation, if applicable.

    • items.taxes optional

      List of tax rules to apply to the item. Normally populated by tax settings.

      Show taxes arguments
      • items.taxes.id required

        Unique identifier for the object. Should refer to one of the IDs in the cart taxes object.

      • items.taxes.amount required

        Fixed tax amount.

    • items.variant_id optional

      ID of the item variant, if applicable.

  • shipping optional

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

    Show shipping arguments
    • shipping.account_address_id optional

      Setting this value will populate shipping with the associated customer's account address on file.

    • shipping.address1 optional

      Shipping address line 1 (street address/PO box/company name).

    • shipping.address2 optional

      Shipping address line 2 (apartment/suite/unit/building).

    • shipping.city optional

      Shipping city/district/suberb/town/village.

    • shipping.country optional

      Two-letter ISO code country code.

    • shipping.default optional

      Indicates shipping details represent the customer's default shipping address.

    • shipping.first_name optional

      Shipping first name. If name is updated, then first_name will be automatically updated as the first word of the name.

    • shipping.last_name optional

      Shipping last name. If name is updated, then last_name will be automatically updated as the last words of the name.

    • shipping.name optional

      Shipping full name. If first_name or last_name are updated, then name will be automatically updated as a combination of first/last.

    • shipping.phone optional

      Shipping phone number.

    • shipping.price optional

      Price of the shipping service. Defaults to shipment_rating.services.price chosen by setting service.

    • shipping.service optional

      ID of a shipping service as configured in shipment settings. Normally, this would be applied after retrieving shipping rates by using one of the shipment_rating.services.id values.

    • shipping.state optional

      Shipping state/county/province/region.

    • shipping.zip optional

      Shipping zip/postal code.

  • Show all arguments
    • account_credit_amount optional

      When applying gift cards to a cart, optionally indicate the total amount to spend from all gift cards applied. Defaults to the maximum amount available up to grand_total. Specifying an amount greater than the total available will return a validation error.

    • account_info_saved optional

      Set true when the customer has indicated they want to save shipping and billing information to their account for future use.

    • account_logged_in optional

      Set true when the customer has logged in with a password before submitting the order. This affects whether the order is considered as a guest checkout.

    • comments optional

      Customer notes provided when placing the order, if any.

    • coupon_id optional

      ID of the coupon applied to the cart.

    • date_abandoned optional

      Date the cart was or will be marked as abandoned.

    • date_abandoned_next optional

      Next date the cart will be marked as abandoned when using a series of abandoned cart recovery notices (a.k.a Advanced Cart Recovery).

    • discounts optional

      List of discounts to apply to the cart.

      Show discounts arguments
      • discounts.id optional

        Unique identifier for the object.

      • discounts.amount optional

        Fixed discount amount.

      • discounts.rule optional

        Object describing the discount rule details. Custom discounts don't require this value.

      • discounts.type optional

        Type of discount. Can be coupon or promo-<id> referring to the source of the discount. Custom discounts don't require this value.

    • gift_message optional

      Optional message to include with the order when shipping to the recipient.

    • giftcards optional

      List of gift cards to apply to the cart.

      Show giftcards arguments
      • giftcards.amount optional

        Amount of the gift card balance to spend on this order. Defaults to giftcard.balance.

      • giftcards.code optional

        Specify a gift card code to apply to the cart. If the code is not found or invalid, a validation error is returned. Case-insensitive.

    • gift optional

      Set true when the order is indented as a gift for the recipient.

    • guest optional

      Set true when the cart is a guest checkout. Defaults to not(account_logged_in).

    • item_tax_included optional

      Indicates line item prices include taxes.

    • notes optional

      Internal admin notes. These are not visible to the customer.

    • promotion_ids optional

      Set a list of promotion IDs to apply to the cart, or null to clear all promotions.

    • recovered optional

      Set true to indicate the cart was recovered and converted to an order after being abandoned.

    • shipment_discount optional

      Shipping discount applied by coupons, promotions or custom logic.

    • shipment_tax_included optional

      Indicates shipping total includes taxes, if applicable.

    • shipment_tax optional

      Shipping tax amount, if applicable.

    • taxes optional

      List of taxes to apply to the cart.

      Show taxes arguments
      • taxes.id optional

        Unique identifier for the object.

      • taxes.amount optional

        Fixed tax amount.

      • taxes.name optional

        Name of the tax rule, for example "NY Sales Tax".

      • taxes.rate optional

        Tax percentage used in calculating the fixed amount.

      • taxes.shipping optional

        Indicates the tax applies to shipping.

Returns

Returns the updated cart if valid arguments are provided, otherwise returns an object containing validation errors.

Convert cart to an order

POST /orders

$ curl https://api.swell.store/orders \
  -u store-id:secret-key \
  -d cart_id=5cad15bc9b14d1990724663a \
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.post('/orders', {
  cart_id: '5cad15bc9b14d1990724663a',
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->post('/orders', [
  'cart_id' => '5cad15bc9b14d1990724663a',
]);

Example response

{
  "id": "5cad15bc9b14d1990724663b",
  "account_id": "5a9ea7ba3f95740a914267f1",
  "billing": {...},
  "cart_id": "5cad15bc9b14d1990724663a",
  "shipping": {...},
  "items": [
    {
      "id": "5a9ea7ba3f95740a914267f2",
      "product_id": "5cad15bc9b14d1990724663b",
      "quantity": 2,
      "price": 9.99,
      "price_total": 18.98,
      "shipment_weight": 1.5,
      ...
    }
  ],
  "coupon_code": "FREESHIPPING",
  "currency": "USD",
  "date_created": "2019-04-01T00:00:00.000Z",
  "delivered": false,
  "discount_total": 0,
  "grand_total": 18.98,
  "item_quantity": 2,
  "item_shipment_weight": 3.0,
  "item_tax": 0,
  "number": "100101",
  "paid": false,
  "payment_balance": -18.98,
  "payment_total": 0,
  "refund_total": 0,
  "refunded": false,
  "shipment_price": 0,
  "shipment_total": 0,
  "status": "payment_pending",
  "sub_total": 0,
  "tax_total": 0,
  ...
}

Create a new order from an active cart. This call Will map items and other properties from a cart while creating the order and mark the cart as converted. Returns an error if any of the required order properties are missing from the cart, or if product stock is unavailable.

Arguments

  • cart_id optional

    ID of the cart to convert.

List all carts

GET /carts

$ curl https://api.swell.store/carts?where[active]=true&limit=25&page=1 \
  -u store-id:secret-key \
  -G
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/carts', {
  where: { active: true },
  limit: 25,
  page: 1,
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->get('/carts', [
  'where' => [ 'active' => true ],
  'limit' => 25,
  'page' => 1,
]);

Example response

{
  "count": 51,
  "results": [
    {
      "id": "5cad15bc9b14d1990724663a",
      "active": true,
      "billing": {...},
      "shipping": {
        "name": "Jon Snow",
        "first_name": "Jon",
        "last_name": "Snow",
        "address1": "1 Main Street",
        "city": "Brooklyn",
        "state": "NY",
        "zip": "11201",
        "country": "US",
        "phone": "(555) 555-5555"
      },
      "items": [
        {
          "id": "5a9ea7ba3f95740a914267f2",
          "product_id": "5cad15bc9b14d1990724663b",
          "quantity": 2,
          "price": 9.99,
          "price_total": 18.98,
          "shipment_weight": 1.5,
          ...
        }
      ],
      "coupon_code": "FREESHIPPING",
      "currency": "USD",
      "date_created": "2019-04-01T00:00:00.000Z",
      "date_updated": "2019-04-01T00:00:00.000Z",
      "discount_total": 0,
      "grand_total": 18.98,
      "item_quantity": 2,
      "item_shipment_weight": 3.0,
      "item_tax": 0,
      "number": "100101",
      "shipment_price": 0,
      "shipment_total": 0,
      "status": "active",
      "sub_total": 0,
      "tax_total": 0,
      ...
    },
    {...},
    {...}
  ],
  "page": 1,
  "pages": {
    "1": {
      "start": 1,
      "end": 25
    },
    "2": {
      "start": 26,
      "end": 50
    },
    "2": {
      "start": 51,
      "end": 51
    }
  }
}

Return a list of carts.

Arguments

  • expand optional

    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.

  • fields optional

    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 cart id is always returned.

  • include optional

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

  • limit optional

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

  • page optional

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

  • search optional

    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.

  • sort optional

    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.

  • where optional

    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.

Returns

An object with an array of results containing up to the limit and matching filters specified. If no records are found given the page and limit arguments, the results array will be empty. This request should never throw an error.

Delete a cart

DELETE /carts/:id

$ curl https://api.swell.store/carts/5cad15bc9b14d1990724663a \
  -u store-id:secret-key \
  -X DELETE
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.delete('/carts/{id}', {
  id: '5cad15bc9b14d1990724663a',
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->delete('/carts/{id}', [
  'id' => '5cad15bc9b14d1990724663a',
]);

Example response

{
  "id": "5cad15bc9b14d1990724663a",
  "active": true,
  "billing": {...},
  "shipping": {
    "name": "Jon Snow",
    "first_name": "Jon",
    "last_name": "Snow",
    "address1": "1 Main Street",
    "city": "Brooklyn",
    "state": "NY",
    "zip": "11201",
    "country": "US",
    "phone": "(555) 555-5555"
  },
  "items": [
    {
      "id": "5a9ea7ba3f95740a914267f2",
      "product_id": "5cad15bc9b14d1990724663b",
      "quantity": 2,
      "price": 9.99,
      "price_total": 18.98,
      "shipment_weight": 1.5,
      ...
    }
  ],
  "coupon_code": "FREESHIPPING",
  "currency": "USD",
  "date_created": "2019-04-01T00:00:00.000Z",
  "date_updated": "2019-04-01T00:00:00.000Z",
  "discount_total": 0,
  "grand_total": 18.98,
  "item_quantity": 2,
  "item_shipment_weight": 3.0,
  "item_tax": 0,
  "number": "100101",
  "shipment_price": 0,
  "shipment_total": 0,
  "status": "active",
  "sub_total": 0,
  "tax_total": 0,
  ...
}

Delete a cart permanently.

Arguments

  • id required

    ID of the cart to delete.

Returns

Returns the original cart if the operation was successful, or null if the cart was not found.

Orders

An order is a request to purchase products from a store. Orders contain all the information needed to fulfill a purchase. Usually, customers create a cart to stage a purchase first, and see it converted to an order when it's finalized. Besides being converted from a cart, it is possible to create an order directly.

The order model

The order object

{
  "id": "5f626b0d91f0af999b00003d",
  "account_id": "5f626b0d91f0af999b000041",
  "account_info_saved": true,
  "account_logged_in": true,
  "authorized_payment_id": true,
  "billing": {
    "name": "Jon Snow",
    "first_name": "Jon",
    "last_name": "Snow",
    "address1": "1 Main Street",
    "city": "Brooklyn",
    "state": "NY",
    "zip": 11201,
    "country": "US",
    "phone": "(555) 555-5555",
    "method": "card",
    "card": {
      "token": "card_1Ds1K7E30PFlZWil6Q7bJ1PD",
      "test": true,
      "last4": "4242",
      "brand": "Visa",
      "address_check": "unchecked",
      "zip_check": "unchecked",
      "cvc_check": "unchecked",
      "exp_month": 1,
      "exp_year": 2029,
      "fingerprint": "3e63991847bbdaafdbc5c8f110ad803f"
    },
    "account_card_id": "5c3ac9870b3b171a7dfaf089"
  },
  "cart_id": "5f626b0d91f0af999b00003f",
  "comments": null,
  "coupon_code": "WINTERSALE",
  "coupon_id": "5f626b0d91f0af999b000040",
  "currency": "USD",
  "date_created": "2020-09-16T19:44:13.735Z",
  "date_updated": "2020-09-16T19:44:13.735Z",
  "date_webhook_first_failed": null,
  "delivered": true,
  "discount_total": 5,
  "discounts": [
    {
      "id": "coupon-0",
      "type": "coupon",
      "amount": 5,
      "rule": {
        "type": "product",
        "value_type": "fixed",
        "value_amount": 2.5,
        "product_id": "5c524166f4e8f3446a10331b"
      }
    }
  ],
  "gift_message": null,
  "gift": true,
  "giftcard_total": 25,
  "giftcards": [
    {
      "id": "5841c5691c64c63e75d29e43",
      "amount": 25,
      "code": "B6UQY3DHRCM4BQYU",
      "code_formatted": "B6UQ Y3DH RCM4 BQYU",
      "last4": "BQYU"
    }
  ],
  "grand_total": 41.98,
  "guest": false,
  "hold": false,
  "item_discount": 5,
  "item_quantity_canceled": 0,
  "item_quantity_deliverable": 0,
  "item_quantity_delivered": 2,
  "item_quantity_giftcard_deliverable": 0,
  "item_quantity_shipment_deliverable": 0,
  "item_quantity_subscription_deliverable": 0,
  "item_quantity": 2,
  "item_shipment_weight": 2,
  "item_tax": 2,
  "items": [
    {
      "id": "5ca537326a0ec32a521139dd",
      "product_id": "5c524166f4e8f3446a10331b",
      "variant_id": "5c524166f4e8f3446a10331f",
      "quantity": 2,
      "price": 19.99,
      "price_total": 38.98,
      "orig_price": 19.99,
      "delivery": "shipment",
      "shipment_weight": 1,
      "options": [
        {
          "id": "5becb84fac207653a4816ee5",
          "name": "Size",
          "value": "Small",
          "variant": true
        },
        {
          "id": "5becb84fac207653a4816ee6",
          "name": "Color",
          "value": "Yellow",
          "variant": true
        }
      ],
      "discounts": [
        {
          "id": "coupon-0",
          "amount": 5
        }
      ],
      "discount_each": 2.5,
      "discount_total": 5,
      "taxes": [
        {
          "id": "sales-tax",
          "amount": 2
        }
      ],
      "tax_each": 1,
      "tax_total": 2,
      "quantity_canceled": 0,
      "quantity_delivered": 2,
      "quantity_deliverable": 0,
      "quantity_shipment_deliverable": 0
    }
  ],
  "notes": null,
  "number": 2039485,
  "paid": true,
  "payment_balance": 0,
  "payment_marked": true,
  "payment_total": 41.98,
  "promotion_ids": null,
  "refund_total": 0,
  "refunded": false,
  "shipment_delivery": true,
  "shipment_discount": 0,
  "shipment_price": 5,
  "shipment_rating": {
    "fingerprint": "71e03117e684192f4f33569dab1c74ee",
    "services": [
      {
        "id": "standard",
        "name": "Standard Shipping",
        "price": 5
      },
      {
        "id": "express",
        "name": "Express Shipping",
        "price": 10
      },
      {
        "id": "next_day",
        "name": "Next Day Shipping",
        "price": 20
      }
    ],
    "errors": null
  },
  "shipment_tax_included_total": 5,
  "shipment_total": 5,
  "shipping": {
    "name": "Jon Snow",
    "first_name": "Jon",
    "last_name": "Snow",
    "address1": "1 Main Street",
    "city": "Brooklyn",
    "state": "NY",
    "zip": 11201,
    "country": "US",
    "phone": "(555) 555-5555",
    "price": 5,
    "service": "standard",
    "service_name": "Standard",
    "account_address_id": "5c12c5fdfcd74b34e19cf659"
  },
  "status": "complete",
  "sub_total": 38.98,
  "tax_total": 2,
  "taxes": [
    {
      "id": "sales-tax",
      "name": "Sales tax",
      "priority": 1,
      "rate": 0.1,
      "amount": 2
    }
  ],
  "webhook_attempts_failed": null,
  "webhook_response": null,
  "webhook_status": 200
}

Fields

  • id objectid

    Unique identifier for the order.

  • account_id objectid

    ID of the customer's account.

  • account_credit_amount currency

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

  • account_info_saved bool

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

  • account_logged_in bool

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

  • account link

    Expandable link to the customer's account.

  • authorized_payment link

    Expandable link to an authorized payment.

  • authorized_payment_id auto string

    ID of an authorized payment. When "Require payment authorization" is enabled in payment settings, the order will be rejected if initial payment fails.

  • billing object

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

    Show billing fields
    • billing.account_card_id objectid

      ID of the customer's credit card on file, if applicable.

    • billing.account_card link

      Expandable link to the customer's credit card on file, if applicable.

    • billing.address1 string

      Billing address line 1 (street address/PO box/company name).

    • billing.address2 string

      Billing address line 2 (apartment/suite/unit/building).

    • billing.amazon object

      Amazon billing details used when billing.method=amazon.

      Show amazon fields
      • billing.amazon.access_token string

        Amazon access token provided when a customer authorizes payment in a storefront.

      • billing.amazon.order_reference_id string

        Amazon order reference ID created when a customer initiates payment in a storefront.

    • billing.card object

      Credit card billing details used when billing.method=card.

      Show card fields
      • billing.card.token string

        Token generated by Swell Checkout or Stripe.js.

      • billing.card.address_check string

        When used with a payment gateway that performs address checks and address1 was provided, can be pass, fail, unavailable or unchecked.

      • billing.card.brand string

        Credit card brand. Can be American Express, Diners Club, Discover, JCB, MasterCard, UnionPay, Visa, or Unknown.

      • billing.card.cvc_check string

        When used with a payment gateway that performs CVC code checks and cvc was provided, can be pass, fail, unavailable or unchecked.

      • billing.card.exp_month int

        Two-digit number representing the credit card expiration month.

      • billing.card.exp_year int

        Four-digit number representing the credit card expiration year.

      • billing.card.last4 string

        Last four digits of the card number.

      • billing.card.zip_check string

        When used with a payment gateway that performs address checks and zip was provided, can be pass, fail, unavailable or unchecked.

    • billing.city string

      Billing city/district/suberb/town/village.

    • billing.country string

      Two-letter ISO code country code.

    • billing.default bool

      Indicates billing details represent the customer's default payment method.

    • billing.first_name string

      Billing first name. If name is updated, then first_name will be automatically updated as the first word of the name.

    • billing.last_name string

      Billing last name. If name is updated, then last_name will be automatically updated as the last words of the name.

    • billing.method string

      Method of payment. Can be card, account, amazon, paypal or any one of the manual methods defined in payment settings.

    • billing.name string

      Billing full name. If first_name or last_name are updated, then name will be automatically updated as a combination of first/last.

    • billing.paypal object

      PayPal billing details used when billing.method=paypal.

      Show paypal fields
      • billing.paypal.payer_id string

        PayPal payer ID provided when a customer authorizes payment in a storefront.

      • billing.paypal.payment_id string

        PayPal payment ID created when a customer initiates payment in a storefront.

    • billing.phone string

      Billing phone number.

    • billing.state string

      Billing state/county/province/region.

    • billing.zip string

      Billing zip/postal code.

  • cancel_reason string

    A message describing the reason for cancelling the order, if applicable.

  • canceled bool

    Indicates the order was completely canceled.

  • cart link

    Expandable link to the cart.

  • cart_id auto objectid

    ID of the cart that converted to this order, if applicable.

  • comments string

    Customer notes provided when placing the order, if any.

  • coupon link

    Expandable link to the coupon applied to the order.

  • coupon_code string

    Coupon code applied to the order. See coupons for details.

  • coupon_id objectid

    ID of the coupon applied to the order.

  • currency auto string

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

  • date_canceled date

    Date the order was canceled, if applicable.

  • date_created auto date

    Date and time the order was created.

  • date_period_end auto date

    Period end date applicable when the order was created from a subscription.

  • date_period_start auto date

    Period start date applicable when the order was created from a subscription.

  • date_updated auto date

    Date and time the order was last updated.

  • date_webhook_first_failed auto date

    Date the order webhook first failed, if applicable. Value is unset after an order webhook is successfully returned for the record.

  • delivered auto bool, default: false

    Indicates the order was completely fulfilled. Always true when delivery_marked=true, otherwise depends on the sum of shipments, giftcards and subscriptions.

  • delivery_marked bool

    Indicates the order was marked as fulfilled, manually or automatically.

  • discount_total auto currency

    Total discount amount.

  • discounts array

    List of discounts applied to the order.

    Show discounts fields
    • discounts.id string

      Unique identifier for the object.

    • discounts.amount currency

      Fixed discount amount.

    • discounts.rule object

      Object describing the discount rule details. Custom discounts don't require this value.

    • discounts.type string

      Type of discount. Can be coupon or promo-<id> referring to the source of the discount. Custom discounts don't require this value.

  • gift_message string

    Optional message to include with the order when shipping to the recipient.

  • gift bool

    Indicates the order is intended as a gift for the recipient.

  • giftcard_delivery bool

    Indicates the order has at least one line item with delivery=giftcard.

  • giftcard_total auto currency

    Total payment amount applied to the order from giftcards.

  • giftcards array

    List of gift cards applied to the order.

    Show giftcards fields
    • giftcards.id objectid

      Unique identifier for the object.

    • giftcards.amount currency

      Amount of the gift card balance to spend for initial payment. If not specified, each gift cards will be spent in order until payment is completed.

    • giftcards.code_formatted string

      Fully formatted gift card code for display purposes.

    • giftcards.code string

      Gift card code to apply. A validation error will be returned if the code is not valid.

    • giftcards.giftcard link

      Expandable link to the gift card record.

    • giftcards.last4 string

      Last four digits of the gift card code.

  • grand_total auto currency

    Grand total including items, shipping and taxes.

  • guest bool

    Indicates the customer was not logged in when placing the order.

  • hold bool, default: false

    Indicates the order was placed on hold.

  • item_discount auto currency

    Total discount applied to line items.

  • item_quantity_canceled auto int

    Total quantity of line items canceled.

  • item_quantity_deliverable auto int

    Total quantity of line items that can be fulfilled.

  • item_quantity_delivered auto int

    Total quantity of line items that have been fulfilled.

  • item_quantity_giftcard_deliverable auto int

    Total quantity of line items that can be fulfilled by gift card. Applies when item.delivery=giftcard.

  • item_quantity_shipment_deliverable auto int

    Total quantity of line items that can be fulfilled by shipment. Applies when item.delivery=shipment.

  • item_quantity_subscription_deliverable auto int

    Total quantity of line items that can be fulfilled by subscription. Applies when item.delivery=subscription.

  • item_quantity auto int

    Total quantity of all line items.

  • item_shipment_weight auto float

    Total shipping weight of all line items.

  • item_tax_included bool

    Indicates line item prices include taxes.

  • item_tax auto currency

    Total taxes applied to line items.

  • items array

    List of line items describing the products ordered.

    Show items fields
    • items.id objectid

      Unique identifier for the item.

    • items.bundle_items array

      List of items offered as a bundle. Defaults to product.bundle_items.

      Show bundle_items fields
      • items.bundle_items.id objectid

        Unique identifier for the object.

      • items.bundle_items.product_id objectid

        ID of the bundle item product.

      • items.bundle_items.delivery string

        Method of delivery taken automatically from product.delivery.

      • items.bundle_items.product link

        Expandable link to the bundle item product.

      • items.bundle_items.quantity_canceled int

        Quantity of the bundle item canceled before fulfillment, if applicable.

      • items.bundle_items.quantity_consumed int

        Quantity of stock consumed by the bundle item, if applicable.

      • items.bundle_items.quantity_deliverable int

        Quantity of the bundle item that can be fulfilled, if applicable.

      • items.bundle_items.quantity_delivered int

        Quantity of the bundle item that has been fulfilled, if applicable.

      • items.bundle_items.quantity_giftcard_deliverable int

        Quantity of the bundle item that can be fulfilled by a gift card. Applies when delivery=giftcard.

      • items.bundle_items.quantity_shipment_deliverable int

        Quantity of the bundle item that can be fulfilled by a shipment. Applies when delivery=shipment.

      • items.bundle_items.quantity_subscription_deliverable int

        Quantity of the bundle item that can be fulfilled by a subscription. Applies when delivery=subscription.

      • items.bundle_items.quantity_total int

        Total quantity of the bundle item to be fulfilled, calculated as item.quantity * bundle_item.quantity.

      • items.bundle_items.quantity int

        Quantity of the bundle item being ordered. Defaults to 1.

      • items.bundle_items.shipment_weight float

        Shipping weight taken automatically from product.shipment_weight, if applicable.

      • items.bundle_items.variant_id objectid

        ID of the bundle item variant.

      • items.bundle_items.variant link

        Expandable link to the bundle item variant.

    • items.delivery string

      Method of delivery taken automatically from product.delivery.

    • items.description string

      Description used for custom line items, when product is not defined.

    • items.discount_each currency

      Total discount amount divided by quantity.

    • items.discount_total currency

      Total discount applied to the item.

    • items.discounts array

      List of discounts applied to the item by coupons, promotions or custom logic.

      Show discounts fields
      • items.discounts.id string

        Unique identifier for the object. Refers to one of the IDs in the order discounts object.

      • items.discounts.amount currency

        Fixed discount amount.

    • items.options array

      Item options matching one or more of product.options. When adding to the order, you can specify the either option id or name (case-insensitive) to identify the option.

      Gift card products have two special options that can be used when fulfilling gift cards by email. Use the option ID send_email and value as the recipient email address, and send_note as a custom message from the customer to the recipient sent by email.

      Show options fields
      • items.options.id string

        Unique identifier for the object.

      • items.options.name string

        Name of the product option. Populated automatically when adding an option by ID.

      • items.options.price currency

        Additional price added onto the base price of the product.

      • items.options.shipment_weight float

        Additional shipping weight added onto the base weight of the product.

      • items.options.subscription bool

        Indicates the option refers to a subscription plan interval.

      • items.options.value string

        Name value of the product option. When adding to the order, specify either the product option value id or name (case-insensitive) to identify the value.

      • items.options.variant bool

        Indicates the option refers to a variant aspect.

    • items.orig_price currency

      Original item price used internally to determine if the item price was overridden and should be automatically updated when item options are changed.

    • items.price_total currency

      Total price added to sub total by multiplying quantity and price.

    • items.price currency

      Price of the item. If a product price is reduced by a sale or price rule, this would be set to the reduced price automatically. Also, item price can be overridden when adding to an order. Line item prices don't change unless explicitly edited by a store admin.

    • items.product_id objectid

      ID of the item product.

    • items.product link

      Expandable link to the item product.

    • items.quantity_canceled int

      Quantity of the item canceled before fulfillment, if applicable.

    • items.quantity_consumed int

      Quantity of stock consumed by the item, if applicable.

    • items.quantity_deliverable int

      Quantity of the item that can be fulfilled, if applicable.

    • items.quantity_delivered int

      Quantity of the item that has been fulfilled, if applicable.

    • items.quantity_giftcard_deliverable int

      Quantity of the item that can be fulfilled by a gift card. Applies when delivery=giftcard.

    • items.quantity int

      Quantity of the item being ordered. Defaults to 1.

    • items.quantity_shipment_deliverable int

      Quantity of the item that can be fulfilled by a shipment. Applies when delivery=shipment.

    • items.quantity_subscription_deliverable int

      Quantity of the item that can be fulfilled by a subscription. Applies when delivery=subscription.

    • items.shipment_weight float

      Shipping weight taken automatically from product.shipment_weight, if applicable.

    • items.subscription_interval string

      Refers to the subscription interval that applies when delivery=subscription.

    • items.subscription_interval_count int

      Refers to the subscription interval count that applies when delivery=subscription.

    • items.subscription_paid bool

      Indicates the item has been fulfilled as a subscription and marked as paid by reference to this order.

    • items.subscription_trial_days int

      Refers to the subscription trial period that applies when delivery=subscription.

    • items.tax_each currency

      Total tax amount divided by quantity.

    • items.tax_total currency

      Total tax applied to the item.

    • items.taxes array

      List of tax rules applied to the item based on tax settings or custom logic.

      Show taxes fields
      • items.taxes.id string

        Unique identifier for the object. Refers to one of the IDs in the order taxes object.

      • items.taxes.amount currency

        Fixed tax amount.

    • items.variant link

      Expandable link to the item variant, if applicable.

    • items.variant_id objectid

      ID of the item variant, if applicable.

  • notes string

    Internal admin notes, not visible to the customer.

  • notifications link

    Expandable list of notifications sent on behalf of the order.

  • number auto string

    Unique incremental order number, assigned automatically using a format configured in general settings.

  • paid auto bool, default: false

    Indicates the order was paid in full. Always true when payment_marked=true, otherwise depends on the sum of payments.

  • payment_balance auto currency

    Balance of payments. A negative number indicates payment is owed, while a positive balance indicates refund is due. Zero balance indicates fully paid.

  • payment_marked bool

    Indicates the order was marked as paid, manually or automatically.

  • payment_total currency, default: 0

    Sum of payments applied to the order, not including refunds.

  • payments link

    Expandable list of payments applied to the order.

  • promotion_ids array

    List of promotion IDs applied to the order.

  • promotions link

    Expandable list of promotions applied to the order.

  • refund_marked bool

    Indicates the order was marked as refunded, manually or automatically.

  • refund_total currency, default: 0

    Sum of refunds on payments applied to the order.

  • refunded auto bool, default: false

    Indicates the order was fully refunded. Always true when refund_marked=true, otherwise depends on the sum of refunds.

  • refunds link

    Expandable list of refunds applied to the order.

  • shipment_delivery bool

    Indicates the order has at least one line item with delivery=shipment.

  • shipment_discount currency

    Shipping discount applied by coupons, promotions or custom logic.

  • shipment_price auto currency

    Total shipping price before discounts.

  • shipment_rating auto object

    Object describing the shipping services and rates available for the order. Shipping country must be set before retrieving shipping rates.

    Show shipment_rating fields
    • shipment_rating.date_created date

      Date and time the object was created.

    • shipment_rating.errors array

      List of errors generated while retrieving rates, if any. When using 3rd party shipping services, any system errors will be listed here.

      Show errors fields
      • shipment_rating.errors.code string

        Unique code describing the error.

      • shipment_rating.errors.message string

        Message describing the error.

    • shipment_rating.fingerprint string

      Unique fingerprint identifying the parameters used to calculate shipping rates. Rates should always be the same given the same parameters and shipping settings.

    • shipment_rating.services array

      List of shipping services and rates available.

      Show services fields
      • shipment_rating.services.id string

        Unique identifier for the object.

      • shipment_rating.services.carrier string

        Name of a 3rd party carrier offering the service, if applicable.

      • shipment_rating.services.name string

        Name of the shipping service.

      • shipment_rating.services.price currency

        Price of the shipping service.

  • shipment_tax currency

    Shipping tax amount, if applicable.

  • shipment_tax_included bool

    Indicates shipping total includes taxes, if applicable.

  • shipment_tax_included_total auto currency

    Total shipping price including taxes and discount. Allows for an alternate display style as normally shipment_total and tax_total are shown separately.

  • shipment_total auto currency

    Total shipping price after discounts.

  • shipments link

    Expandable list of shipments created from the order.

  • shipping object

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

    Show shipping fields
    • shipping.account_address_id objectid

      ID of the customer's address on file.

    • shipping.account_address link

      Expandable link to the customer's address on file.

    • shipping.address1 string

      Shipping address line 1 (street address/PO box/company name).

    • shipping.address2 string

      Shipping address line 2 (apartment/suite/unit/building).

    • shipping.city string

      Shipping city/district/suberb/town/village.

    • shipping.country string

      Two-letter ISO code country code.

    • shipping.default bool

      Indicates shipping details represent the customer's default shipping address.

    • shipping.first_name string

      Shipping first name. If name is updated, then first_name will be automatically updated as the first word of the name.

    • shipping.last_name string

      Shipping last name. If name is updated, then last_name will be automatically updated as the last words of the name.

    • shipping.name string

      Shipping full name. If first_name or last_name are updated, then name will be automatically updated as a combination of first/last.

    • shipping.phone string

      Shipping phone number.

    • shipping.price currency

      Price of the shipping service. Defaults to shipment_rating.services.price chosen by setting service.

    • shipping.service_name string

      Name of the shipping service. Defaults to shipment_rating.services.name chosen by setting service.

    • shipping.service string

      ID of a shipping service as configured in shipment settings. Normally, this would be applied after retrieving shipping rates by using one of the shipment_rating.services.id values.

    • shipping.state string

      Shipping state/county/province/region.

    • shipping.zip string

      Shipping zip/postal code.

  • status auto string, default: pending

    Current status of the order. Can be pending, draft, payment_pending, delivery_pending, hold, complete or canceled.

  • sub_total auto currency

    Sum of all line items before discounts, taxes and shipping.

  • subscription link

    Expandable link to the subscription that spawned the order, if applicable.

  • subscription_delivery bool

    Indicates the order has at least one line item with delivery=subscription.

  • subscription_id auto objectid

    ID of the subscription that spawned the order, if applicable.

  • tax_included_total auto currency

    Total of taxes applied separately from line items.

  • tax_total auto currency

    Total tax amount applied to the order including line items and shipping.

  • taxes array

    List of taxes applied to the order.

    Show taxes fields
    • taxes.id string

      Unique identifier for the object.

    • taxes.amount currency

      Fixed tax amount.

    • taxes.name string

      Name of the tax rule, for example "NY Sales Tax".

    • taxes.priority int

      Priority indicates the order in which a tax rule was applied. Higher priority rules are added on top of other tax rules with a lower priority. Rules with the same priority are calculated excluding each other.

    • taxes.rate float

      Tax percentage used in calculating the fixed amount.

    • taxes.shipping bool

      Indicates the tax applies to shipping.

  • webhook_attempts_failed auto int

    Number of failed order webhook attempts, if applicable. Value is unset after an order webhook is successfully returned for the record.

  • webhook_response auto string

    Text response of the last failed order webhook attempt, if applicable. Value is unset after an order webhook is successfully returned for the record.

  • webhook_status auto int

    HTTP response status of the last failed order webhook attempt, if applicable. Value is unset after an order webhook is successfully returned for the record.

Create an order

POST /orders

$ curl https://api.swell.store/orders \
  -u store-id:secret-key \
  -d account_id=5a9ea7ba3f95740a914267f1 \
  -d items[0][product_id]=5cad15bc9b14d1990724663a \
  -d items[0][quantity]=2 \
  -d coupon_code=FREESHIPPING
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.post('/orders', {
  account_id: '5a9ea7ba3f95740a914267f1',
  items: [
    {
      product_id: '5cad15bc9b14d1990724663a',
      quantity: 2,
    }
  ],
  billing: {
    ...
  },
  shipping: {
    ...
  },
  coupon_code: 'FREESHIPPING',
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->post('/orders', [
  'items' => [
    [
      'product_id' => '5cad15bc9b14d1990724663a',
      'quantity' => 2,
    ]
  ],
  'account_id' => '5a9ea7ba3f95740a914267f1',
  'billing' => [
    ...
  ],
  'shipping' => [
    ...
  ],
  'coupon_code' => 'FREESHIPPING',
]);

Example response

{
  "id": "5cad15bc9b14d1990724663a",
  "account_id": "5a9ea7ba3f95740a914267f1",
  "billing": {...},
  "shipping": {...},
  "items": [
    {
      "id": "5a9ea7ba3f95740a914267f2",
      "product_id": "5cad15bc9b14d1990724663b",
      "quantity": 2,
      "price": 9.99,
      "price_total": 18.98,
      "shipment_weight": 1.5,
      ...
    }
  ],
  "coupon_code": "FREESHIPPING",
  "currency": "USD",
  "date_created": "2019-04-01T00:00:00.000Z",
  "delivered": false,
  "discount_total": 0,
  "grand_total": 18.98,
  "item_quantity": 2,
  "item_shipment_weight": 3.0,
  "item_tax": 0,
  "number": "100101",
  "paid": false,
  "payment_balance": -18.98,
  "payment_total": 0,
  "refund_total": 0,
  "refunded": false,
  "shipment_price": 0,
  "shipment_total": 0,
  "status": "payment_pending",
  "sub_total": 0,
  "tax_total": 0,
  ...
}

Create a new order.

Arguments

  • account_id required

    ID of the customer's account.

  • billing optional

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

    Show billing arguments
    • billing.account_card_id optional

      Setting this value will populate billing.card with the associated customer's credit card on file.

    • billing.address1 optional

      Billing address line 1 (street address/PO box/company name).

    • billing.address2 optional

      Billing address line 2 (apartment/suite/unit/building).

    • billing.amazon optional

      Amazon billing details used when billing.method=amazon.

      Show amazon arguments
      • billing.amazon.access_token optional

        Amazon access token provided when a customer authorizes payment in a storefront.

      • billing.amazon.order_reference_id optional

        Amazon order reference ID created when a customer initiates payment in a storefront.

    • billing.card optional

      Credit card billing details used when billing.method=card.

      Show card arguments
      • billing.card.token required

        Token generated by Swell Checkout or Stripe.js.

      • billing.card.brand optional

        Credit card brand. Can be American Express, Diners Club, Discover, JCB, MasterCard, UnionPay, Visa, or Unknown.

      • billing.card.exp_month optional

        Two-digit number representing the credit card expiration month.

      • billing.card.exp_year optional

        Four-digit number representing the credit card expiration year.

      • billing.card.last4 optional

        Last four digits of the card number.

    • billing.city optional

      Billing city/district/suberb/town/village.

    • billing.country optional

      Two-letter ISO code country code.

    • billing.first_name optional

      Billing first name. If name is updated, then first_name will be automatically updated as the first word of the name.

    • billing.last_name optional

      Billing last name. If name is updated, then last_name will be automatically updated as the last words of the name.

    • billing.method optional

      Method of payment. Can be card, account, amazon, paypal or any one of the manual methods defined in payment settings.

    • billing.name optional

      Billing full name. If first_name or last_name are updated, then name will be automatically updated as a combination of first/last.

    • billing.paypal optional

      PayPal billing details used when billing.method=paypal.

      Show paypal arguments
      • billing.paypal.payer_id optional

        PayPal payer ID provided when a customer authorizes payment in a storefront.

      • billing.paypal.payment_id optional

        PayPal payment ID created when a customer initiates payment in a storefront.

    • billing.phone optional

      Billing phone number.

    • billing.state optional

      Billing state/county/province/region.

    • billing.zip optional

      Billing zip/postal code.

  • coupon_code optional

    Set to a valid coupon code to apply the coupon's discount. If the code is not found or invalid, a validation error is returned.

  • items optional

    List of line items describing the products ordered.

    Show items arguments
    • items.bundle_items optional

      List of items offered as a bundle. Defaults to product.bundle_items.

      Show bundle_items arguments
      • items.bundle_items.product_id required

        ID of the bundle item product.

      • items.bundle_items.quantity optional

        Quantity of the bundle item being ordered. Defaults to 1.

      • items.bundle_items.shipment_weight optional

        Weight to be used in shipping calculation, if applicable.

      • items.bundle_items.variant_id optional

        ID of the bundle item variant.

    • items.description optional

      Description used for custom line items, when product is not defined.

    • items.discounts optional

      List of discounts to apply to the item. Normally populated by applying a coupon or promotions.

      Show discounts arguments
      • items.discounts.id required

        Unique identifier for the object. Should refer to one of the IDs in the order discounts object.

      • items.discounts.amount required

        Fixed discount amount.

    • items.options optional

      Item options matching one or more of product.options. When adding to the order, you can specify the either option id or name (case-insensitive) to identify the option.

      Gift card products have two special options that can be used when fulfilling gift cards by email. Use the option ID send_email and value as the recipient email address, and send_note as a custom message from the customer to the recipient sent by email.

      Show options arguments
      • items.options.id optional

        Unique identifier for the object.

      • items.options.name optional

        Name of the product option. Populated automatically when adding an option by ID.

      • items.options.price optional

        Additional price added onto the base price of the product.

      • items.options.shipment_weight optional

        Additional shipping weight added onto the base weight of the product.

      • items.options.subscription optional

        Indicates the option refers to a subscription plan interval.

      • items.options.value optional

        Name value of the product option. When adding to the order, specify either the product option value id or name (case-insensitive) to identify the value.

      • items.options.variant optional

        Indicates the option refers to a variant aspect.

    • items.price optional

      Price of the item. Override this value to set a custom price. Defaults to product price or sale price.

    • items.product_id optional

      ID of the item product.

    • items.quantity optional

      Quantity of the item being ordered. Defaults to 1.

    • items.shipment_weight optional

      Weight to be used in shipping calculation, if applicable.

    • items.taxes optional

      List of tax rules to apply to the item. Normally populated by tax settings.

      Show taxes arguments
      • items.taxes.id required

        Unique identifier for the object. Should refer to one of the IDs in the order taxes object.

      • items.taxes.amount required

        Fixed tax amount.

    • items.variant_id optional

      ID of the item variant, if applicable.

  • shipping optional

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

    Show shipping arguments
    • shipping.account_address_id optional

      Setting this value will populate shipping with the associated customer's account address on file.

    • shipping.address1 optional

      Shipping address line 1 (street address/PO box/company name).

    • shipping.address2 optional

      Shipping address line 2 (apartment/suite/unit/building).

    • shipping.city optional

      Shipping city/district/suberb/town/village.

    • shipping.country optional

      Two-letter ISO code country code.

    • shipping.default optional

      Indicates shipping details represent the customer's default shipping address.

    • shipping.first_name optional

      Shipping first name. If name is updated, then first_name will be automatically updated as the first word of the name.

    • shipping.last_name optional

      Shipping last name. If name is updated, then last_name will be automatically updated as the last words of the name.

    • shipping.name optional

      Shipping full name. If first_name or last_name are updated, then name will be automatically updated as a combination of first/last.

    • shipping.phone optional

      Shipping phone number.

    • shipping.price optional

      Price of the shipping service. Defaults to shipment_rating.services.price chosen by setting service.

    • shipping.service optional

      ID of a shipping service as configured in shipment settings. Normally, this would be applied after retrieving shipping rates by using one of the shipment_rating.services.id values.

    • shipping.state optional

      Shipping state/county/province/region.

    • shipping.zip optional

      Shipping zip/postal code.

  • Show all arguments
    • account_credit_amount optional

      When applying gift cards to an order, optionally indicate the total amount to spend from all gift cards applied. Defaults to the maximum amount available up to grand_total. Specifying an amount greater than the total available will return a validation error.

    • account_info_saved optional

      Set true when the customer has indicated they want to save shipping and billing information to their account for future use.

    • account_logged_in optional

      Set true when the customer has logged in with a password before submitting the order. This affects whether the order is considered as a guest checkout.

    • cancel_reason optional

      A message describing the reason for cancelling the order, if applicable.

    • canceled optional

      Set true to cancel the order, notifying the customer by email and returning stock quantity if applicable.

    • comments optional

      Customer notes provided when placing the order, if any.

    • coupon_id optional

      ID of the coupon applied to the order.

    • date_canceled optional

      Date the order was canceled, if applicable.

    • delivery_marked optional

      Set true mark the order as completely fulfilled, regardless of fulfillment records.

    • discounts optional

      List of discounts to apply to the order.

      Show discounts arguments
      • discounts.id optional

        Unique identifier for the object.

      • discounts.amount optional

        Fixed discount amount.

      • discounts.rule optional

        Object describing the discount rule details. Custom discounts don't require this value.

      • discounts.type optional

        Type of discount. Can be coupon or promo-<id> referring to the source of the discount. Custom discounts don't require this value.

    • gift_message optional

      Optional message to include with the order when shipping to the recipient.

    • giftcards optional

      List of gift cards to apply to the order.

      Show giftcards arguments
      • giftcards.amount optional

        Amount of the gift card balance to spend on this order. Defaults to giftcard.balance.

      • giftcards.code optional

        Specify a gift card code to apply to the order. If the code is not found or invalid, a validation error is returned. Case-insensitive.

    • gift optional

      Set true when the order is indented as a gift for the recipient.

    • guest optional

      Set true when the order is placed by guest checkout. Defaults to not(account_logged_in).

    • hold optional

      Set true to put the order "on hold" and prevent automated fulfillment, if applicable.

    • item_tax_included optional

      Indicates line item prices include taxes.

    • notes optional

      Internal admin notes, not visible to the customer.

    • payment_marked optional

      Set true mark the order as fully paid, regardless of payment records.

    • promotion_ids optional

      Set a list of promotion IDs to apply to the order, or null to clear all promotions.

    • refund_marked optional

      Set true mark the order as fully refunded, regardless of refund records.

    • shipment_discount optional

      Shipping discount applied by coupons, promotions or custom logic.

    • shipment_tax_included optional

      Indicates shipping total includes taxes, if applicable.

    • shipment_tax optional

      Shipping tax amount, if applicable.

    • taxes optional

      List of taxes to apply to the order.

      Show taxes arguments
      • taxes.id optional

        Unique identifier for the object.

      • taxes.amount optional

        Fixed tax amount.

      • taxes.name optional

        Name of the tax rule, for example "NY Sales Tax".

      • taxes.rate optional

        Tax percentage used in calculating the fixed amount.

      • taxes.shipping optional

        Indicates the tax applies to shipping.

Returns

Returns a new order if valid arguments are provided, otherwise returns an object containing validation errors.

Retrieve an order

GET /orders/:id

$ curl https://api.swell.store/orders/5cad15bc9b14d1990724663a \
  -u store-id:secret-key
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/orders/{id}', {
  id: '5cad15bc9b14d1990724663a',
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->get('/orders/{id}', [
  'id' => '5cad15bc9b14d1990724663a',
]);

Example response

{
  "id": "5cad15bc9b14d1990724663a",
  "account_id": "5a9ea7ba3f95740a914267f1",
  "billing": {...},
  "shipping": {...},
  "items": [
    {
      "id": "5a9ea7ba3f95740a914267f2",
      "product_id": "5cad15bc9b14d1990724663b",
      "quantity": 2,
      "price": 9.99,
      "price_total": 18.98,
      "shipment_weight": 1.5,
      ...
    }
  ],
  "coupon_code": "FREESHIPPING",
  "currency": "USD",
  "date_created": "2019-04-01T00:00:00.000Z",
  "delivered": false,
  "discount_total": 0,
  "grand_total": 18.98,
  "item_quantity": 2,
  "item_shipment_weight": 3.0,
  "item_tax": 0,
  "number": "100101",
  "paid": false,
  "payment_balance": -18.98,
  "payment_total": 0,
  "refund_total": 0,
  "refunded": false,
  "shipment_price": 0,
  "shipment_total": 0,
  "status": "payment_pending",
  "sub_total": 0,
  "tax_total": 0,
  ...
}

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

Arguments

  • id required

    ID of the order to retrieve.

  • expand optional

    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.

  • fields optional

    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 order id is always returned.

  • include optional

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

Returns

Returns a order if a valid ID was provided. Otherwise null.

Update an order

PUT /orders/:id

$ curl https://api.swell.store/orders/5cad15bc9b14d1990724663a \
  -u store-id:secret-key \
  -d name="Jon Snow" \
  -d address1="1 Main Street" \
  -d city=Brooklyn \
  -d state=NY \
  -d zip=11201 \
  -d country=US \
  -d phone="(555) 555-5555" \
  -X PUT
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.put('/orders/{id}', {
  id: '5cad15bc9b14d1990724663a',
  shipping: {
    name: 'Jon Snow',
    address1: '1 Main Street',
    city: 'Brooklyn',
    state: 'NY',
    zip: '11201',
    country: 'US',
    phone: '(555) 555-5555',
  },
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->put('/orders/{id}', [
  'id' => '5cad15bc9b14d1990724663a',
  'shipping' => [
    'name' => 'Jon Snow',
    'address1' => '1 Main Street',
    'city' => 'Brooklyn',
    'state' => 'NY',
    'zip' => '11201',
    'country' => 'US',
    'phone' => '(555) 555-5555'
  ]
]);

Example response

{
  "id": "5cad15bc9b14d1990724663a",
  "account_id": "5a9ea7ba3f95740a914267f1",
  "billing": {...},
  "shipping": {
    "name": "Jon Snow",
    "first_name": "Jon",
    "last_name": "Snow",
    "address1": "1 Main Street",
    "city": "Brooklyn",
    "state": "NY",
    "zip": "11201",
    "country": "US",
    "phone": "(555) 555-5555"
  },
  "items": [
    {
      "id": "5a9ea7ba3f95740a914267f2",
      "product_id": "5cad15bc9b14d1990724663b",
      "quantity": 2,
      "price": 9.99,
      "price_total": 18.98,
      "shipment_weight": 1.5,
      ...
    }
  ],
  "coupon_code": "FREESHIPPING",
  "currency": "USD",
  "date_created": "2019-04-01T00:00:00.000Z",
  "date_updated": "2019-04-01T00:00:00.000Z",
  "delivered": false,
  "discount_total": 0,
  "grand_total": 18.98,
  "item_quantity": 2,
  "item_shipment_weight": 3.0,
  "item_tax": 0,
  "number": "100101",
  "paid": false,
  "payment_balance": -18.98,
  "payment_total": 0,
  "refund_total": 0,
  "refunded": false,
  "shipment_price": 0,
  "shipment_total": 0,
  "status": "payment_pending",
  "sub_total": 0,
  "tax_total": 0,
  ...
}

Update an existing order 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

  • id required

    Unique identifier for the order.

  • account_id optional

    ID of the customer's account.

  • billing optional

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

    Show billing arguments
    • billing.account_card_id optional

      Setting this value will populate billing.card with the associated customer's credit card on file.

    • billing.address1 optional

      Billing address line 1 (street address/PO box/company name).

    • billing.address2 optional

      Billing address line 2 (apartment/suite/unit/building).

    • billing.amazon optional

      Amazon billing details used when billing.method=amazon.

      Show amazon arguments
      • billing.amazon.access_token optional

        Amazon access token provided when a customer authorizes payment in a storefront.

      • billing.amazon.order_reference_id optional

        Amazon order reference ID created when a customer initiates payment in a storefront.

    • billing.card optional

      Credit card billing details used when billing.method=card.

      Show card arguments
      • billing.card.token required

        Token generated by Swell Checkout or Stripe.js.

      • billing.card.brand optional

        Credit card brand. Can be American Express, Diners Club, Discover, JCB, MasterCard, UnionPay, Visa, or Unknown.

      • billing.card.exp_month optional

        Two-digit number representing the credit card expiration month.

      • billing.card.exp_year optional

        Four-digit number representing the credit card expiration year.

      • billing.card.last4 optional

        Last four digits of the card number.

    • billing.city optional

      Billing city/district/suberb/town/village.

    • billing.country optional

      Two-letter ISO code country code.

    • billing.first_name optional

      Billing first name. If name is updated, then first_name will be automatically updated as the first word of the name.

    • billing.last_name optional

      Billing last name. If name is updated, then last_name will be automatically updated as the last words of the name.

    • billing.method optional

      Method of payment. Can be card, account, amazon, paypal or any one of the manual methods defined in payment settings.

    • billing.name optional

      Billing full name. If first_name or last_name are updated, then name will be automatically updated as a combination of first/last.

    • billing.paypal optional

      PayPal billing details used when billing.method=paypal.

      Show paypal arguments
      • billing.paypal.payer_id optional

        PayPal payer ID provided when a customer authorizes payment in a storefront.

      • billing.paypal.payment_id optional

        PayPal payment ID created when a customer initiates payment in a storefront.

    • billing.phone optional

      Billing phone number.

    • billing.state optional

      Billing state/county/province/region.

    • billing.zip optional

      Billing zip/postal code.

  • coupon_code optional

    Set to a valid coupon code to apply the coupon's discount. If the code is not found or invalid, a validation error is returned.

  • items optional

    List of line items describing the products ordered.

    Show items arguments
    • items.bundle_items optional

      List of items offered as a bundle. Defaults to product.bundle_items.

      Show bundle_items arguments
      • items.bundle_items.product_id required

        ID of the bundle item product.

      • items.bundle_items.quantity optional

        Quantity of the bundle item being ordered. Defaults to 1.

      • items.bundle_items.shipment_weight optional

        Weight to be used in shipping calculation, if applicable.

      • items.bundle_items.variant_id optional

        ID of the bundle item variant.

    • items.description optional

      Description used for custom line items, when product is not defined.

    • items.discounts optional

      List of discounts to apply to the item. Normally populated by applying a coupon or promotions.

      Show discounts arguments
      • items.discounts.id required

        Unique identifier for the object. Should refer to one of the IDs in the order discounts object.

      • items.discounts.amount required

        Fixed discount amount.

    • items.options optional

      Item options matching one or more of product.options. When adding to the order, you can specify the either option id or name (case-insensitive) to identify the option.

      Gift card products have two special options that can be used when fulfilling gift cards by email. Use the option ID send_email and value as the recipient email address, and send_note as a custom message from the customer to the recipient sent by email.

      Show options arguments
      • items.options.id optional

        Unique identifier for the object.

      • items.options.name optional

        Name of the product option. Populated automatically when adding an option by ID.

      • items.options.price optional

        Additional price added onto the base price of the product.

      • items.options.shipment_weight optional

        Additional shipping weight added onto the base weight of the product.

      • items.options.subscription optional

        Indicates the option refers to a subscription plan interval.

      • items.options.value optional

        Name value of the product option. When adding to the order, specify either the product option value id or name (case-insensitive) to identify the value.

      • items.options.variant optional

        Indicates the option refers to a variant aspect.

    • items.price optional

      Price of the item. Override this value to set a custom price. Defaults to product price or sale price.

    • items.product_id optional

      ID of the item product.

    • items.quantity optional

      Quantity of the item being ordered. Defaults to 1.

    • items.shipment_weight optional

      Weight to be used in shipping calculation, if applicable.

    • items.taxes optional

      List of tax rules to apply to the item. Normally populated by tax settings.

      Show taxes arguments
      • items.taxes.id required

        Unique identifier for the object. Should refer to one of the IDs in the order taxes object.

      • items.taxes.amount required

        Fixed tax amount.

    • items.variant_id optional

      ID of the item variant, if applicable.

  • shipping optional

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

    Show shipping arguments
    • shipping.account_address_id optional

      Setting this value will populate shipping with the associated customer's account address on file.

    • shipping.address1 optional

      Shipping address line 1 (street address/PO box/company name).

    • shipping.address2 optional

      Shipping address line 2 (apartment/suite/unit/building).

    • shipping.city optional

      Shipping city/district/suberb/town/village.

    • shipping.country optional

      Two-letter ISO code country code.

    • shipping.default optional

      Indicates shipping details represent the customer's default shipping address.

    • shipping.first_name optional

      Shipping first name. If name is updated, then first_name will be automatically updated as the first word of the name.

    • shipping.last_name optional

      Shipping last name. If name is updated, then last_name will be automatically updated as the last words of the name.

    • shipping.name optional

      Shipping full name. If first_name or last_name are updated, then name will be automatically updated as a combination of first/last.

    • shipping.phone optional

      Shipping phone number.

    • shipping.price optional

      Price of the shipping service. Defaults to shipment_rating.services.price chosen by setting service.

    • shipping.service optional

      ID of a shipping service as configured in shipment settings. Normally, this would be applied after retrieving shipping rates by using one of the shipment_rating.services.id values.

    • shipping.state optional

      Shipping state/county/province/region.

    • shipping.zip optional

      Shipping zip/postal code.

  • Show all arguments
    • account_credit_amount optional

      When applying gift cards to an order, optionally indicate the total amount to spend from all gift cards applied. Defaults to the maximum amount available up to grand_total. Specifying an amount greater than the total available will return a validation error.

    • account_info_saved optional

      Set true when the customer has indicated they want to save shipping and billing information to their account for future use.

    • account_logged_in optional

      Set true when the customer has logged in with a password before submitting the order. This affects whether the order is considered as a guest checkout.

    • cancel_reason optional

      A message describing the reason for cancelling the order, if applicable.

    • canceled optional

      Set true to cancel the order, notifying the customer by email and returning stock quantity if applicable.

    • comments optional

      Customer notes provided when placing the order, if any.

    • coupon_id optional

      ID of the coupon applied to the order.

    • date_canceled optional

      Date the order was canceled, if applicable.

    • delivery_marked optional

      Set true mark the order as completely fulfilled, regardless of fulfillment records.

    • discounts optional

      List of discounts to apply to the order.

      Show discounts arguments
      • discounts.id optional

        Unique identifier for the object.

      • discounts.amount optional

        Fixed discount amount.

      • discounts.rule optional

        Object describing the discount rule details. Custom discounts don't require this value.

      • discounts.type optional

        Type of discount. Can be coupon or promo-<id> referring to the source of the discount. Custom discounts don't require this value.

    • gift_message optional

      Optional message to include with the order when shipping to the recipient.

    • giftcards optional

      List of gift cards to apply to the order.

      Show giftcards arguments
      • giftcards.amount optional

        Amount of the gift card balance to spend on this order. Defaults to giftcard.balance.

      • giftcards.code optional

        Specify a gift card code to apply to the order. If the code is not found or invalid, a validation error is returned. Case-insensitive.

    • gift optional

      Set true when the order is indented as a gift for the recipient.

    • guest optional

      Set true when the order is placed by guest checkout. Defaults to not(account_logged_in).

    • hold optional

      Set true to put the order "on hold" and prevent automated fulfillment, if applicable.

    • item_tax_included optional

      Indicates line item prices include taxes.

    • notes optional

      Internal admin notes, not visible to the customer.

    • payment_marked optional

      Set true mark the order as fully paid, regardless of payment records.

    • promotion_ids optional

      Set a list of promotion IDs to apply to the order, or null to clear all promotions.

    • refund_marked optional

      Set true mark the order as fully refunded, regardless of refund records.

    • shipment_discount optional

      Shipping discount applied by coupons, promotions or custom logic.

    • shipment_tax_included optional

      Indicates shipping total includes taxes, if applicable.

    • shipment_tax optional

      Shipping tax amount, if applicable.

    • taxes optional

      List of taxes to apply to the order.

      Show taxes arguments
      • taxes.id optional

        Unique identifier for the object.

      • taxes.amount optional

        Fixed tax amount.

      • taxes.name optional

        Name of the tax rule, for example "NY Sales Tax".

      • taxes.rate optional

        Tax percentage used in calculating the fixed amount.

      • taxes.shipping optional

        Indicates the tax applies to shipping.

Returns

Returns the updated order if valid arguments are provided, otherwise returns an object containing validation errors.

List all orders

GET /orders

$ curl https://api.swell.store/orders?where[account_id]=592ef41c57ce232e1ce3729e&limit=25&page=1 \
  -u store-id:secret-key \
  -G
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/orders', {
  where: {
    account_id: '592ef41c57ce232e1ce3729e',
  },
  limit: 25,
  page: 1,
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->get('/orders', [
  'where' => [
    'account_id' => '592ef41c57ce232e1ce3729e'
  ],
  'limit' => 25,
  'page' => 1,
]);

Example response

{
  "count": 51,
  "results": [
    {
      "id": "5cad15bc9b14d1990724663a",
      "account_id": "5a9ea7ba3f95740a914267f1",
      "billing": {...},
      "shipping": {
        "name": "Jon Snow",
        "first_name": "Jon",
        "last_name": "Snow",
        "address1": "1 Main Street",
        "city": "Brooklyn",
        "state": "NY",
        "zip": "11201",
        "country": "US",
        "phone": "(555) 555-5555"
      },
      "items": [
        {
          "id": "5a9ea7ba3f95740a914267f2",
          "product_id": "5cad15bc9b14d1990724663b",
          "quantity": 2,
          "price": 9.99,
          "price_total": 18.98,
          "shipment_weight": 1.5,
          ...
        }
      ],
      "coupon_code": "FREESHIPPING",
      "currency": "USD",
      "date_created": "2019-04-01T00:00:00.000Z",
      "date_updated": "2019-04-01T00:00:00.000Z",
      "delivered": false,
      "discount_total": 0,
      "grand_total": 18.98,
      "item_quantity": 2,
      "item_shipment_weight": 3.0,
      "item_tax": 0,
      "number": "100101",
      "paid": false,
      "payment_balance": -18.98,
      "payment_total": 0,
      "refund_total": 0,
      "refunded": false,
      "shipment_price": 0,
      "shipment_total": 0,
      "status": "payment_pending",
      "sub_total": 0,
      "tax_total": 0,
      ...
    },
    {...},
    {...}
  ],
  "page": 1,
  "pages": {
    "1": {
      "start": 1,
      "end": 25
    },
    "2": {
      "start": 26,
      "end": 50
    },
    "2": {
      "start": 51,
      "end": 51
    }
  }
}

Return a list of orders.

Arguments

  • expand optional

    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.

  • fields optional

    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 order id is always returned.

  • include optional

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

  • limit optional

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

  • page optional

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

  • search optional

    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.

  • sort optional

    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.

  • where optional

    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.

Returns

An object with an array of results containing up to the limit and matching filters specified. If no records are found given the page and limit arguments, the results array will be empty. This request should never throw an error.

Delete an order

DELETE /orders/:id

$ curl https://api.swell.store/orders/5cad15bc9b14d1990724663a \
  -u store-id:secret-key \
  -X DELETE
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.delete('/orders/{id}', {
  id: '5cad15bc9b14d1990724663a',
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->delete('/orders/{id}', [
  'id' => '5cad15bc9b14d1990724663a',
]);

Example response

{
  "id": "5cad15bc9b14d1990724663a",
  "account_id": "5a9ea7ba3f95740a914267f1",
  "billing": {...},
  "shipping": {
    "name": "Jon Snow",
    "first_name": "Jon",
    "last_name": "Snow",
    "address1": "1 Main Street",
    "city": "Brooklyn",
    "state": "NY",
    "zip": "11201",
    "country": "US",
    "phone": "(555) 555-5555"
  },
  "items": [
    {
      "id": "5a9ea7ba3f95740a914267f2",
      "product_id": "5cad15bc9b14d1990724663b",
      "quantity": 2,
      "price": 9.99,
      "price_total": 18.98,
      "shipment_weight": 1.5,
      ...
    }
  ],
  "coupon_code": "FREESHIPPING",
  "currency": "USD",
  "date_created": "2019-04-01T00:00:00.000Z",
  "date_updated": "2019-04-01T00:00:00.000Z",
  "delivered": false,
  "discount_total": 0,
  "grand_total": 18.98,
  "item_quantity": 2,
  "item_shipment_weight": 3.0,
  "item_tax": 0,
  "number": "100101",
  "paid": false,
  "payment_balance": -18.98,
  "payment_total": 0,
  "refund_total": 0,
  "refunded": false,
  "shipment_price": 0,
  "shipment_total": 0,
  "status": "payment_pending",
  "sub_total": 0,
  "tax_total": 0,
  ...
}

Delete an order permanently.

Arguments

  • id required

    ID of the order to delete.

Returns

Returns the original order if the operation was successful, or null if the order was not found.

Payments

When a store accepts payment of any kind, a record is kept along with its relation to an order or invoice. Related orders and invoices are automatically updated with payment totals. When a refund is issued, the amount_refunded is also updated.

The payment model

The payment object

{
  "id": "5f626b0d91f0af999b000056",
  "account_id": "5f626b0d91f0af999b00005a",
  "amount": 50,
  "method": "card",
  "account_card_id": "5f626b0d91f0af999b000058",
  "amount_refundable": 30,
  "amount_refunded": 20,
  "async": false,
  "authorized": true,
  "captured": true,
  "card": {
    "token": "card_1Ds1K7E30PFlZWil6Q7bJ1PD",
    "test": true,
    "last4": "4242",
    "brand": "Visa",
    "address_check": "unchecked",
    "zip_check": "unchecked",
    "cvc_check": "unchecked",
    "exp_month": 1,
    "exp_year": 2029
  },
  "currency": "USD",
  "date_created": "2020-09-16T19:44:13.768Z",
  "date_updated": "2020-09-16T19:44:13.768Z",
  "error": null,
  "gateway": "stripe",
  "number": 2973512,
  "order_id": "5f626b0d91f0af999b000059",
  "status": "success",
  "success": true,
  "test": true,
  "transaction_id": "ch_1XNoXdEAeofUkt5SrbA6Swow"
}

Fields

  • id objectid

    Unique identifier for the payment.

  • account_id objectid

    ID of the customer's account the payment was made for.

  • amount currency

    Payment amount denominated in currency.

  • method string

    Method of payment. Can be card, account, amazon, paypal or any one of the manual methods defined in payment settings.

  • account link

    Expandable link to the customer's account that made the payment.

  • account_card_id objectid

    ID of the customer's credit card on file used to make the payment, if applicable.

  • account_card link

    Expandable link to the customer's credit card on file used to make the payment, if applicable.

  • amazon object

    Amazon billing details used when method=amazon.

    Show amazon fields
    • amazon.access_token string

      Amazon access token provided when a customer authorizes payment in a storefront.

    • amazon.order_reference_id string

      Amazon order reference ID created when a customer initiates payment in a storefront.

  • amount_refundable auto currency

    Remaining amount that can be refunded.

  • amount_refunded auto currency

    Amount of the payment that has been refunded.

  • async auto bool

    Indicates the payment is processed asynchronously. The payment will be updated in the future while success is undefined.

  • authorized bool

    Indicates the payment was authorized before being captured.

  • captured bool

    Indicates the payment has been captured.

  • card object

    Credit card details used to make the payment, if applicable.

    Show card fields
    • card.token string

      A temp token generated by Swell Checkout or Stripe.js, or a permanent card token assigned after submitting a temporary token (starting with card_).

    • card.address_check string

      When used with a payment gateway that performs address checks and address1 was provided, can be pass, fail, unavailable or unchecked.

    • card.brand string

      Credit card brand. Can be American Express, Diners Club, Discover, JCB, MasterCard, UnionPay, Visa, or Unknown.

    • card.cvc_check string

      When used with a payment gateway that performs CVC code checks and cvc was provided, can be pass, fail, unavailable or unchecked.

    • card.exp_month int

      Two-digit number representing the credit card expiration month.

    • card.exp_year int

      Four-digit number representing the credit card expiration year.

    • card.last4 string

      Last four digits of the card number.

    • card.zip_check string

      When used with a payment gateway that performs address checks and zip was provided, can be pass, fail, unavailable or unchecked.

  • currency string

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

  • date_created auto date

    Date and time the payment was created.

  • date_updated auto date

    Date and time the payment was last updated.

  • error object

    An object describing an error that occurred while interacting with the payment gateway, if applicable.

    Show error fields
    • error.code string

      Unique error code.

    • error.message string

      A message describing the error.

  • gateway auto string

    ID of the payment gateway that was used to process the payment.

  • giftcard_id objectid

    ID of the gift card used to make the payment, if applicable.

  • giftcard link

    Expandable link to gift card used to make the payment, if applicable.

  • invoice_id objectid

    ID of the invoice the payment was applied to, if applicable.

  • invoice link

    Expandable link to the invoice the payment was applied to, if applicable.

  • number auto string

    Unique incremental payment number assigned automatically.

  • order_id objectid

    ID of the order the payment was applied to, if applicable.

  • order link

    Expandable link to the order the payment was applied to, if applicable.

  • paypal object

    PayPal billing details used when billing.method=paypal.

    Show paypal fields
    • paypal.payer_id string

      PayPal payer ID provided when a customer authorizes payment in a storefront.

    • paypal.payment_id string

      PayPal payment ID created when a customer initiates payment in a storefront.

  • refunds collection

    Expandable list of refunds issued for the payment.

  • status auto string, default: pending

    Status of the payment. Can be pending, error, success or authorized. A pending payment is awaiting async processing.

  • subscription link

    Expandable link to the subscription the payment was applied to, if applicable.

  • subscription_id auto objectid

    ID of the subscription the payment was applied to, if applicable.

  • success bool

    Indicates the payment was successful. When an error occurs with a payment gateway, this status will be false and error field will be populated.

  • test auto bool

    Indicates the payment was made with a gateway in test mode.

  • transaction_id auto string

    External identifier returned by a payment gateway, if applicable.

Create a payment

POST /payments

$ curl https://api.swell.store/payments \
  -u store-id:secret-key \
  -d amount=50 \
  -d method=card \
  -d card[token]=card_XfqLq5nRdOdu7vTvoeKufafN \
  -d acocunt_id=5c899d4f7d7920749638dc4e
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.post('/payments', {
  amount: 50,
  method: 'card',
  card: { token: 'card_XfqLq5nRdOdu7vTvoeKufafN' },
  account_id: '5c899d4f7d7920749638dc4e',
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->post('/payments', [
  'amount' => 50,
  'method' => 'card',
  'card' => [ 'token' => 'card_XfqLq5nRdOdu7vTvoeKufafN' ],
  'account_id' => '5c899d4f7d7920749638dc4e',
  'order_id' => '5cae685b20a54174dd968077',
]);

Example response

{
  "id": "5cae685b20a54174dd968afa",
  "account_id": "5c899d4f7d7920749638dc4e",
  "amount": 50,
  "amount_refundable": 50,
  "authorized": true,
  "captured": true,
  "card": {
    "brand": "Visa",
    "last4": "4242",
    "exp_month": 10,
    "exp_year": 2029,
    "token": "card_XfqLq5nRdOdu7vTvoeKufafN",
    "cvc_check": "pass",
    "zip_check": "pass",
    "address_check": "pass"
  },
  "currency": "USD",
  "date_created": "2019-04-01T00:00:00.000Z",
  "date_updated": "2019-04-01T00:00:00.000Z",
  "gateway": "stripe",
  "method": "card",
  "number": "1947367",
  "order_id": "5cae685b20a54174dd968077",
  "status": "success",
  "success": true,
  "transaction_id": "ch_1XNoXdEAeofUkt5SrbA6Swow"
}

Create a new payment.

Arguments

  • account_id required

    ID of the customer's account to make the payment for.

  • amount required

    Payment amount denominated in currency.

  • method required

    Method of payment. Can be card, account, amazon, paypal or any one of the manual methods defined in payment settings.

  • card optional

    Credit card details used to make the payment, if applicable.

    Show card arguments
    • card.token required

      A temp token generated by Swell Checkout or Stripe.js, or a permanent card token assigned after submitting a temporary token (starting with card_).

    • card.brand optional

      Credit card brand. Can be American Express, Diners Club, Discover, JCB, MasterCard, UnionPay, Visa, or Unknown.

    • card.exp_month optional

      Two-digit number representing the credit card expiration month.

    • card.exp_year optional

      Four-digit number representing the credit card expiration year.

    • card.last4 optional

      Last four digits of the card number.

  • invoice_id optional

    ID of an invoice to apply the payment to, if applicable. Required if order_id is not defined.

  • order_id optional

    ID of an order to apply the payment to. Required if invoice_id is not defined.

  • Show all arguments
    • account_card_id optional

      ID of a customer's credit card to make the payment with. Only applies when method=card. Must be one of the cards belonging to account_id.

    • amazon optional

      Amazon billing details used when method=amazon.

      Show amazon arguments
      • amazon.access_token optional

        Amazon access token provided when a customer authorizes payment in a storefront.

      • amazon.order_reference_id optional

        Amazon order reference ID created when a customer initiates payment in a storefront.

    • authorized optional

      Indicates the payment was authorized before being captured.

    • captured optional

      Indicates the payment has been captured.

    • currency optional

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

    • error optional

      An object describing an error that occurred while interacting with the payment gateway, if applicable.

      Show error arguments
      • error.code optional

        Unique error code.

      • error.message optional

        A message describing the error.

    • giftcard_id optional

      ID of the gift card used to make the payment, if applicable.

    • paypal optional

      PayPal billing details used when billing.method=paypal.

      Show paypal arguments
      • paypal.payer_id optional

        PayPal payer ID provided when a customer authorizes payment in a storefront.

      • paypal.payment_id optional

        PayPal payment ID created when a customer initiates payment in a storefront.

    • success optional

      Indicates the payment was successful. When an error occurs with a payment gateway, this status will be false and error field will be populated.

Returns

Returns a new payment if valid arguments are provided, otherwise returns an object containing validation errors.

Retrieve a payment

GET /payments/:id

$ curl https://api.swell.store/payments/5cae685b20a54174dd968afa \
  -u store-id:secret-key
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/payments/{id}', {
  id: '5cae685b20a54174dd968afa',
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->get('/payments/{id}', [
  'id' => '5cae685b20a54174dd968afa',
]);

Example response

{
  "id": "5cae685b20a54174dd968afa",
  "account_id": "5c899d4f7d7920749638dc4e",
  "amount": 50,
  "amount_refundable": 50,
  "authorized": true,
  "captured": true,
  "card": {
    "brand": "Visa",
    "last4": "4242",
    "exp_month": 10,
    "exp_year": 2029,
    "token": "card_XfqLq5nRdOdu7vTvoeKufafN",
    "cvc_check": "pass",
    "zip_check": "pass",
    "address_check": "pass"
  },
  "currency": "USD",
  "date_created": "2019-04-01T00:00:00.000Z",
  "date_updated": "2019-04-01T00:00:00.000Z",
  "gateway": "stripe",
  "method": "card",
  "number": "1947367",
  "order_id": "5cae685b20a54174dd968077",
  "status": "success",
  "success": true,
  "transaction_id": "ch_1XNoXdEAeofUkt5SrbA6Swow"
}

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

Arguments

  • id required

    ID of the payment to retrieve.

  • expand optional

    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.

  • fields optional

    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 payment id is always returned.

  • include optional

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

Returns

Returns a payment if a valid ID was provided. Otherwise null.

Refund a payment

POST /payments/:id/refunds

$ curl https://api.swell.store/payments/5cae685b20a54174dd968afa/refunds \
  -u store-id:secret-key \
  -d amount=50
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.post('/payments/{id}/refunds', {
  id: '5cae685b20a54174dd968afa',
  amount: 50,
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->post('/payments/{id}/refunds', [
  'id' => '5cae685b20a54174dd968afa',
  'amount' => 50
]);

Example response

{
  "id": "5cae042722984c53002096ab",
  "amount": 50,
  "card": {
    "brand": "Visa",
    "last4": "4242",
    "exp_month": 10,
    "exp_year": 2029,
    "token": "card_XfqLq5nRdOdu7vTvoeKufafN",
    "cvc_check": "pass",
    "zip_check": "pass",
    "address_check": "pass"
  },
  "currency": "USD",
  "date_created": "2019-04-01T00:00:00.000Z",
  "gateway": "stripe",
  "method": "card",
  "number": "103352",
  "order_id": "5cae685b20a54174dd968077",
  "parent_id": "5cae685b20a54174dd968afa",
  "status": "success",
  "success": true,
  "transaction_id": "re_1XNhqtFAeoMUkt5CitcnPNAa"
}

Issue a refund to an existing payment. Available refund up to the original payment amount with any number of calls.

Arguments

  • amount required

    Amount to refund up to payment amount_refundable.

  • method optional

    Optionally refund the payment using a different method. Defaults to the original payment method.

  • reason_message optional

    A brief message describing the reason for the refund.

  • reason optional

Returns

Returns a new refund if valid arguments are provided, otherwise returns an object containing validation errors.

List all payments

GET /payments

$ curl https://api.swell.store/payments?limit=25&page=1 \
  -u store-id:secret-key \
  -G
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/payments', {
  limit: 25,
  page: 1
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->get('/payments', [
  'limit' => 25,
  'page' => 1
]);

Example response

{
  "count": 51,
  "results": [
    {
      "id": "5f626b0d91f0af999b000056",
      "account_id": "5f626b0d91f0af999b00005e",
      "amount": 50,
      "method": "card",
      "account_card_id": "5f626b0d91f0af999b000058",
      "amount_refundable": 30,
      "amount_refunded": 20,
      "async": false,
      "authorized": true,
      "captured": true,
      "card": {
        "token": "card_1Ds1K7E30PFlZWil6Q7bJ1PD",
        "test": true,
        "last4": "4242",
        "brand": "Visa",
        "address_check": "unchecked",
        "zip_check": "unchecked",
        "cvc_check": "unchecked",
        "exp_month": 1,
        "exp_year": 2029
      },
      "currency": "USD",
      "date_created": "2020-09-16T19:44:13.768Z",
      "date_updated": "2020-09-16T19:44:13.768Z",
      "error": null,
      "gateway": "stripe",
      "number": 2973512,
      "order_id": "5f626b0d91f0af999b000059",
      "status": "success",
      "success": true,
      "test": true,
      "transaction_id": "ch_1XNoXdEAeofUkt5SrbA6Swow"
    },
    {...},
    {...}
  ],
  "page": 1,
  "pages": {
    "1": {
      "start": 1,
      "end": 25
    },
    "2": {
      "start": 26,
      "end": 50
    },
    "2": {
      "start": 51,
      "end": 51
    }
  }
}

Return a list of payments

Arguments

  • expand optional

    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.

  • fields optional

    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 payment id is always returned.

  • include optional

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

  • limit optional

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

  • page optional

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

  • search optional

    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.

  • sort optional

    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.

  • where optional

    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.

Returns

An object with an array of results containing up to the limit and matching filters specified. If no records are found given the page and limit arguments, the results array will be empty. This request should never throw an error.

Refunds

Refunds are issued against a payment. The sum of refunds can't exceed the total payment amount. Related orders and invoices are automatically updated with refund totals.

The refund model

The refund object

{
  "id": "5f626b0d91f0af999b000042",
  "amount": 20,
  "method": "card",
  "parent_id": "5f626b0d91f0af999b000045",
  "async": false,
  "currency": "USD",
  "date_created": "2020-09-16T19:44:13.758Z",
  "date_updated": "2020-09-16T19:44:13.758Z",
  "error": null,
  "number": 102934,
  "order_id": "5f626b0d91f0af999b000044",
  "reason_message": "Customer returned EX2001",
  "status": "success",
  "success": true,
  "transaction_id": "re_1XNoXdEAeofUkt5SrbA6Swow"
}

Fields

  • id objectid

    Unique identifier for the refund.

  • amount currency

    Refund amount denominated in currency.

  • method string

    Method of refund. Can be card, account, amazon, paypal or any one of the manual methods defined in payment settings. Defaults to the original payment method.

  • parent_id objectid

    ID of the payment the refund was issued for.

  • async auto bool

    Indicates the refund is processed asynchronously. The refund will be updated in the future while success is undefined.

  • currency string

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

  • date_created auto date

    Date and time the refund was created.

  • date_updated auto date

    Date and time the refund was last updated.

  • error object

    An object describing an error that occurred while interacting with the payment gateway, if applicable.

    Show error fields
    • error.code string

      Unique error code.

    • error.message string

      A message describing the error.

  • number auto string

    Unique incremental refund number assigned automatically.

  • order_id objectid

    ID of the order the refund was applied to, if applicable.

  • order link

    Expandable link to the order the refund was applied to, if applicable.

  • parent link

    Expandable link to the payment.

  • reason_message string

    A brief message describing the reason for the refund.

  • status auto string, default: pending

    Status of the refund. Can be pending, error or success. A pending refund is awaiting async processing.

  • subscription link

    Expandable link to the subscription the refund was applied to, if applicable.

  • subscription_id auto objectid

    ID of the subscription the refund was applied to, if applicable.

  • success bool

    Indicates the refund was successful. When an error occurs with a payment gateway, this value will be false and error field will be populated.

  • transaction_id auto string

    External identifier returned by a payment gateway, if applicable.

Issue a refund

POST /payments:refunds

$ curl https://api.swell.store/payments:refunds \
  -u store-id:secret-key \
  -d amount=20 \
  -d parent_id[_bsontype]=ObjectID \
  -d parent_id[id]=_bk
‘𯙛G \
  -d method=card \

const swell = require('swell-node').init('store-id', 'secret-key');

await swell.post('/payments:refunds', {
  amount: 20,
  parent_id: '5f626b0d91f0af999b000047',
  method: 'card'
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->post('/payments:refunds', [
  'amount' => 20,
  'parent_id' => '5f626b0d91f0af999b000047',
  'method' => 'card'
]);

Example response

{
  "id": "5f626b0d91f0af999b000042",
  "amount": 20,
  "method": "card",
  "parent_id": "5f626b0d91f0af999b00004a",
  "async": false,
  "currency": "USD",
  "date_created": "2020-09-16T19:44:13.758Z",
  "date_updated": "2020-09-16T19:44:13.758Z",
  "error": null,
  "number": 102934,
  "order_id": "5f626b0d91f0af999b000044",
  "reason_message": "Customer returned EX2001",
  "status": "success",
  "success": true,
  "transaction_id": "re_1XNoXdEAeofUkt5SrbA6Swow"
}

To issue a refund, create a refund with the amount and method to return to the customer. A refund can be issued with a different method than the original payment. The total amount refunded can't exceed the total payment amount.

Arguments

  • amount required

    Refund amount denominated in currency.

  • parent_id required

    ID of the payment the refund was issued for.

  • method optional

    Method of refund. Can be card, account, amazon, paypal or any one of the manual methods defined in payment settings. Defaults to the original payment method.

  • Show all arguments
    • currency optional

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

    • error optional

      An object describing an error that occurred while interacting with the payment gateway, if applicable.

      Show error arguments
      • error.code optional

        Unique error code.

      • error.message optional

        A message describing the error.

    • order_id optional

      ID of an order to apply the refund to, if applicable.

    • reason_message optional

      A brief message describing the reason for the refund.

    • success optional

      Indicates the refund was successful. When an error occurs with a payment gateway, this value will be false and error field will be populated.

Returns

Returns a new refund if valid arguments are provided, otherwise returns an object containing validation errors.

Retrieve a refund

GET /payments:refunds/:id

$ curl https://api.swell.store/payments:refunds/5f626b0d91f0af999b00004d \
  -u store-id:secret-key \


const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/payments:refunds/{id}', {
  id: '5f626b0d91f0af999b00004c'
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->get('/payments:refunds/{id}', [
  'id' => '5f626b0d91f0af999b00004c'
]);

Example response

{
  "id": "5f626b0d91f0af999b000050",
  "amount": 20,
  "method": "card",
  "parent_id": "5f626b0d91f0af999b000051",
  "async": false,
  "currency": "USD",
  "date_created": "2020-09-16T19:44:13.758Z",
  "date_updated": "2020-09-16T19:44:13.758Z",
  "error": null,
  "number": 102934,
  "order_id": "5f626b0d91f0af999b000044",
  "reason_message": "Customer returned EX2001",
  "status": "success",
  "success": true,
  "transaction_id": "re_1XNoXdEAeofUkt5SrbA6Swow"
}

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

Arguments

  • id required

    ID of the refund to retrieve.

  • expand optional

    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.

  • fields optional

    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 refund id is always returned.

  • include optional

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

Returns

Returns a refund if a valid ID was provided. Otherwise null.

List all refunds

GET /payments:refunds

$ curl https://api.swell.store/payments:refunds?limit=25&page=1 \
  -u store-id:secret-key \
  -G
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/payments:refunds', {
  limit: 25,
  page: 1
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->get('/payments:refunds', [
  'limit' => 25,
  'page' => 1
]);

Example response

{
  "count": 51,
  "results": [
    {
      "id": "5f626b0d91f0af999b000042",
      "amount": 20,
      "method": "card",
      "parent_id": "5f626b0d91f0af999b000055",
      "async": false,
      "currency": "USD",
      "date_created": "2020-09-16T19:44:13.758Z",
      "date_updated": "2020-09-16T19:44:13.758Z",
      "error": null,
      "number": 102934,
      "order_id": "5f626b0d91f0af999b000044",
      "reason_message": "Customer returned EX2001",
      "status": "success",
      "success": true,
      "transaction_id": "re_1XNoXdEAeofUkt5SrbA6Swow"
    },
    {...},
    {...}
  ],
  "page": 1,
  "pages": {
    "1": {
      "start": 1,
      "end": 25
    },
    "2": {
      "start": 26,
      "end": 50
    },
    "2": {
      "start": 51,
      "end": 51
    }
  }
}

Return a list of refunds.

Arguments

  • expand optional

    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.

  • fields optional

    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 refund id is always returned.

  • include optional

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

  • limit optional

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

  • page optional

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

  • search optional

    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.

  • sort optional

    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.

  • where optional

    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.

Returns

An object with an array of results containing up to the limit and matching filters specified. If no records are found given the page and limit arguments, the results array will be empty. This request should never throw an error.

Subscriptions

Subscriptions

Subscriptions allow to charge a customer on a recurring basis. A subscription ties a customer to a particular subscription plan. In addition to the plan, a subscriptions can have line items that are charged on a recurring basis or just once, depending on particular use case. Orders can be automatically generated every time a subscription is charged by subscribing to a plan with bundle_items.

The subscription model

The subscription object

{
  "id": "5f626b0d91f0af999b000078",
  "account_id": "5f626b0d91f0af999b00007e",
  "product_id": "5f626b0d91f0af999b00007f",
  "active": true,
  "cancel_at_end": false,
  "cancel_reason": null,
  "canceled": false,
  "currency": "USD",
  "date_canceled": null,
  "date_created": "2020-09-16T19:44:13.840Z",
  "date_payment_expiring": "2031-01-01T08:00:00.000Z",
  "date_payment_failed": null,
  "date_payment_retry": null,
  "date_period_end": "2019-03-24T04:28:12.962Z",
  "date_period_start": "2019-02-24T04:28:12.962Z",
  "date_trial_end": "2019-02-24T04:28:12.962Z",
  "date_trial_start": "2019-01-24T04:28:12.962Z",
  "date_updated": "2020-09-16T19:44:13.840Z",
  "discount_total": 0,
  "discounts": null,
  "grand_total": 148.8946,
  "interval": "monthly",
  "interval_count": 1,
  "invoice_total": 99,
  "item_discount": 0,
  "item_tax": 0,
  "item_total": 49.8946,
  "items": [
    {
      "id": "5ca537326a0ec32a521139dd",
      "date_created": "2019-03-24T22:56:33.467Z",
      "description": "Remaining time on Example Subscription",
      "proration": true,
      "quantity": 1,
      "price": 49.8946,
      "price_total": 49.8946,
      "recurring_price": 0,
      "recurring_price_total": 0,
      "discount_total": 0,
      "discount_each": 0,
      "recurring_discount_total": 0,
      "recurring_discount_each": 0,
      "tax_total": 0,
      "tax_each": 0,
      "recurring_tax_total": 0,
      "recurring_tax_each": 0
    }
  ],
  "notes": null,
  "options": [
    {
      "id": "5becb84fac207653a4816ee5",
      "name": "Plan",
      "value": "Monthly"
    }
  ],
  "order_id": "5f626b0d91f0af999b00007b",
  "order_item_id": "5f626b0d91f0af999b00007c",
  "paid": true,
  "payment_balance": 0,
  "payment_total": 99,
  "price": 99,
  "price_total": 99,
  "product_discount_each": 0,
  "product_discount_total": 0,
  "product_discounts": null,
  "product_tax_each": 0,
  "product_tax_total": 0,
  "product_taxes": null,
  "quantity": 1,
  "recurring_discount_total": 0,
  "recurring_item_discount": 0,
  "recurring_item_tax": 0,
  "recurring_item_total": 0,
  "recurring_tax_included_total": 0,
  "recurring_tax_total": 0,
  "recurring_total": 99,
  "refund_total": 0,
  "status": "active",
  "sub_total": 148.8946,
  "tax_included_total": 0,
  "tax_total": 0,
  "taxes": null,
  "trial": false,
  "trial_days": 14,
  "unpaid": false,
  "variant_id": "5f626b0d91f0af999b00007d"
}

Fields

  • id objectid

    Unique identifier for the subscription.

  • account_id objectid

    ID of the subscribed customer's account.

  • product_id objectid

    ID of the subscription plan product.

  • account link

    Expandable link to the subscribed customer's account.

  • active bool, default: false

    Indicates the subscription is currently active.

  • cancel_at_end bool

    When true, indicates the subscription was or will be canceled at the end of the billing period.

  • cancel_reason string

    A brief message describing the reason the subscription was canceled, if applicable.

  • canceled bool

    Indicates the subscription was canceled.

  • coupon_code string

    Coupon code applied to the subscription. See coupons for details.

  • coupon link

    Expandable link to the coupon applied to the subscription.

  • coupon_id objectid

    ID of the coupon applied to the subscription.

  • currency string

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

  • date_canceled date

    Date the subscription was canceled, if applicable.

  • date_created auto date

    Date and time the subscription was created.

  • date_payment_expiring auto date

    Date when the customer's current default credit card will expire, used to notify the customer to update their payment information before their card expires.

  • date_payment_failed date

    Date when the last automated payment failed, if applicable.

  • date_payment_retry auto date

    When automated payment has failed, this is the date when the system will automatically retry.

  • date_period_end auto date

    End date of the current billing period.

  • date_period_start date

    Start date of the current billing period.

  • date_prorated date

    Date the subscription was last prorated, if applicable. Used to calculate the charge or credit applied when the subscription is prorated.

  • date_trial_end date

    Date the trial period did end in the past, or will end in the future. Changing this value can be used to update the billing period of a subscription with or without a trial. For example, to set the monthly billing date to the 1st of the month, update date_trial_end to the first of the next month.

  • date_trial_start date

    Date the trial period started, if applicable.

  • date_updated auto date

    Date and time the subscription was last updated.

  • discount_total auto currency

    Total discount amount.

  • discounts auto array

    List of all discounts applied to the subscription.

    Show discounts fields
    • discounts.id string

      Unique identifier for the object.

    • discounts.amount currency

      Fixed discount amount.

    • discounts.rule object

      Object describing the discount rule details. Custom discounts don't require this value.

    • discounts.type string

      Type of discount. Can be coupon or sale referring to the source of the discount. Custom discounts don't require this value.

  • grand_total auto currency

    Grand total of the next invoice including line items and taxes.

  • interval string

    Billing interval. Can be monthly, daily, weekly or yearly.

  • interval_count int

    Multiplier for billing interval. For example, to make the subscription charge once every 2 weeks, set interval=weekly and interval_count=2.

  • invoice_total currency

    Amount invoiced for the last billing period.

  • invoices link

    Expandable list of all invoices created by the subscription.

  • item_discount auto currency

    Total discount applied to line items.

  • item_tax auto currency

    Total taxes applied to line items.

  • item_total auto currency

  • items array

    List of invoice line items added to the subscription. Recurring items are charged repeatedly, otherwise they are charged on the next invoice and then removed from the subscription.

    Show items fields
    • items.id objectid

      Unique identifier for the object.

    • items.date_created date

      Date and time the object was created.

    • items.description string

      Description used for custom line items, when product is not defined.

    • items.discount_each currency

      Total discount amount divided by quantity.

    • items.discount_total currency

      Total discount applied to the item.

    • items.discounts array

      List of discounts applied to the line item by coupons.

      Show discounts fields
      • items.discounts.id string

        Unique identifier for the object. Refers to one of the IDs in the subscription discounts object.

      • items.discounts.amount currency

        Fixed discount amount.

    • items.options array

      Item options matching one or more of product.options, if applicable. When setting this value, specify either option id or name (case-insensitive) to identify the option.

      Show options fields
      • items.options.id string

        Unique identifier for the object.

      • items.options.name string

        Name of the option. Populated automatically when adding an option by ID.

      • items.options.price currency

        Price of the option added to plan price when selected.

      • items.options.value string

        Name value of the option. When setting this value, specify either the product option value id or name (case-insensitive) to identify the value.

      • items.options.variant bool

        Indicates the option refers to a variant aspect.

    • items.price currency

      Price of the line item. Defaults to product price, if applicable. A negative value will be subtracted from the plan total and credited to the customer on their next invoice.

    • items.price_total currency

      Total price of the line item (price * quantity).

    • items.product_id objectid

      ID of the item product, if applicable.

    • items.product link

      Expandable link to the item product, if applicable.

    • items.proration bool

      Indicates the item represents a proration charge or credit.

    • items.quantity int

      Quantity of the line item.

    • items.recurring_discount_each currency

      Total recurring discount amount divided by quantity, if applicable.

    • items.recurring_discount_total currency

      Total recurring discount applied to the item, if applicable.

    • items.recurring_price_total currency

      Total recurring price of the item (price * quantity), if applicable.

    • items.recurring_price currency

      Recurring price of the item, if applicable.

    • items.recurring_tax_each currency

      Total recurring tax amount divided by quantity, if applicable.

    • items.recurring_tax_total currency

      Total recurring tax applied to the item, if applicable.

    • items.recurring bool

      Indicates the item will remain on the subscription after the next invoice is created.

    • items.tax_each currency

      Total tax amount divided by quantity.

    • items.tax_total currency

      Total tax applied to the item.

    • items.taxes array

      List of tax rules applied to the item based on tax settings.

      Show taxes fields
      • items.taxes.id string

        Unique identifier for the object. Refers to one of the IDs in the subscription taxes object.

      • items.taxes.amount currency

        Fixed tax amount.

    • items.variant link

      Expandable link to the item variant, if applicable.

    • items.variant_id objectid

      ID of the item variant, if applicable.

  • notes string

    Internal admin notes. These are not visible to the customer.

  • options array

    Plan options matching one or more of product.options. When setting this value, specify either option id or name (case-insensitive) to identify the option.

    Show options fields
    • options.id string

      Unique identifier for the object.

    • options.name string

      Name of the plan option. Populated automatically when adding an option by ID.

    • options.price currency

      Price of the option added to plan price when selected.

    • options.value string

      Name value of the plan option. When setting this value, specify either value id or name (case-insensitive) to identify the value.

    • options.variant bool

      Indicates the option refers to a variant aspect.

  • order_id objectid

    ID of the order that originated the subscription, if applicable.

  • order_item_id objectid

    ID of the line item from the order that originated the subscription, if applicable.

  • orders link

    Expandable list of all orders created by the subscription plan. This happens when a plan contains physical products as bundle_items.

  • paid auto bool, default: false

    Indicates the last invoice was fully paid.

  • payment_balance auto currency

    Balance of payments on the invoice for the last billing period. A negative number indicates payment is owed, while a positive balance indicates refund is due. Zero balance indicates the invoice was fully paid.

  • payment_total currency

    Total amount of payments for the last billing period.

  • payments link

    Expandable list of all payments made on behalf of the subscription.

  • pending_invoices link

    Expandable list of invoices that haven't been fully paid.

  • price currency

    Price of the plan. Plan price can be overridden when creating or updating a subscription.

  • price_total auto currency

    Total price of the plan (price * quantity).

  • product link

    Expandable link to the subscription plan product.

  • product_discount_each auto currency

    Total discount amount of the subscription plan, divided by quantity.

  • product_discount_total auto currency

    Total discount applied to the subscription plan.

  • product_discounts auto array

    List of discounts applied to the subscription plan by coupons.

    Show product_discounts fields
    • product_discounts.id string

      Unique identifier for the object. Refers to one of the IDs in the subscription discounts object.

    • product_discounts.amount currency

      Fixed discount amount.

  • product_tax_each auto currency

    Total tax amount of the subscription plan, divided by quantity.

  • product_tax_total auto currency

    Total tax applied to the subscription plan.

  • product_taxes auto array

    List of tax rules applied to the subscription plan based on tax settings.

    Show product_taxes fields
    • product_taxes.id string

      Unique identifier for the object. Refers to one of the IDs in the subscription taxes object.

    • product_taxes.amount currency

      Fixed tax amount.

  • prorated bool

    When false, indicates the subscription should not be prorated if the plan product is changed, otherwise a prorated charge or credit will be added at the appropriate time.

  • quantity int, default: 1

    Quantity of the plan to charge.

  • recurring_discount_total auto currency

    Total recurring discount applied to the subscription including line items.

  • recurring_item_discount auto currency

    Total discount applied to recurring line items.

  • recurring_item_tax auto currency

    Total taxes applied to recurring line items.

  • recurring_item_total auto currency

    Sum of all recurring line items before discounts and taxes.

  • recurring_tax_included_total auto currency

    Total of taxes applied separately from the subscription plan and recurring line items.

  • recurring_tax_total auto currency

    Total taxes applied to the subscription including recurring line items.

  • recurring_total auto currency

    Recurring total of the subscription including line items and taxes.

  • refund_total currency

    Total amount of refunds for the last billing period.

  • refunds link

    Expandable list of all refunds made on behalf of the subscription.

  • status auto string

    Current status of the subscription. Can be pending, active, trial, pastdue, unpaid, canceled or paid.

  • sub_total auto currency

    Sum of all line items before discounts and taxes.

  • tax_included_total auto currency

    Total of taxes applied separately from the subscription plan and line items.

  • tax_included auto bool

    Indicates the subscription plan price includes taxes.

  • tax_total auto currency

    Total taxes applied to the subscription including line items.

  • taxes auto array

    List of taxes applied to the subscription.

    Show taxes fields
    • taxes.id string

      Unique identifier for the object.

    • taxes.amount currency

      Fixed tax amount.

    • taxes.name string

      Name of the tax rule, for example "NY Sales Tax".

    • taxes.priority int

      Priority indicates the order in which a tax rule was applied. Higher priority rules are added on top of other tax rules with a lower priority. Rules with the same priority are calculated excluding each other.

    • taxes.rate float

      Tax percentage used in calculating the fixed amount.

  • trial auto bool

    Indicates the subscription is in a trial period and the first invoice will be issued on date_trial_end.

  • trial_days int

    Number of days the subscription trial period was for. An invoice will not be issued until trial has elapsed.

  • unpaid auto bool, default: false

    Indicates the last invoice was marked as unpaid. This occurs automatically after all payment attempts are exhausted, as configured in subscription settings.

  • variant_id objectid

    ID of the subscription plan variant, if applicable.

  • variant link

    Expandable link to the subscription plan variant, if applicable.

Create a subscription

POST /subscriptions

$ curl https://api.swell.store/subscriptions \
  -u store-id:secret-key \
  -d account_id[_bsontype]=ObjectID \
  -d account_id[id]=_bk
‘𯙛‚ \
  -d product_id[_bsontype]=ObjectID \
  -d product_id[id]=_bk
‘𯙛ƒ \
  -d quantity=1 \
  -d trial_days=14 \

const swell = require('swell-node').init('store-id', 'secret-key');

await swell.post('/subscriptions', {
  account_id: '5f626b0d91f0af999b000082',
  product_id: '5f626b0d91f0af999b000083',
  quantity: 1,
  trial_days: 14
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->post('/subscriptions', [
  'account_id' => '5f626b0d91f0af999b000082',
  'product_id' => '5f626b0d91f0af999b000083',
  'quantity' => 1,
  'trial_days' => 14
]);

Example response

{
  "id": "5f626b0d91f0af999b000078",
  "account_id": "5f626b0d91f0af999b000087",
  "product_id": "5f626b0d91f0af999b000088",
  "active": true,
  "cancel_at_end": false,
  "cancel_reason": null,
  "canceled": false,
  "currency": "USD",
  "date_canceled": null,
  "date_created": "2020-09-16T19:44:13.840Z",
  "date_payment_expiring": "2031-01-01T08:00:00.000Z",
  "date_payment_failed": null,
  "date_payment_retry": null,
  "date_period_end": "2019-03-24T04:28:12.962Z",
  "date_period_start": "2019-02-24T04:28:12.962Z",
  "date_trial_end": "2019-02-24T04:28:12.962Z",
  "date_trial_start": "2019-01-24T04:28:12.962Z",
  "date_updated": "2020-09-16T19:44:13.840Z",
  "discount_total": 0,
  "discounts": null,
  "grand_total": 148.8946,
  "interval": "monthly",
  "interval_count": 1,
  "invoice_total": 99,
  "item_discount": 0,
  "item_tax": 0,
  "item_total": 49.8946,
  "items": [
    {
      "id": "5ca537326a0ec32a521139dd",
      "date_created": "2019-03-24T22:56:33.467Z",
      "description": "Remaining time on Example Subscription",
      "proration": true,
      "quantity": 1,
      "price": 49.8946,
      "price_total": 49.8946,
      "recurring_price": 0,
      "recurring_price_total": 0,
      "discount_total": 0,
      "discount_each": 0,
      "recurring_discount_total": 0,
      "recurring_discount_each": 0,
      "tax_total": 0,
      "tax_each": 0,
      "recurring_tax_total": 0,
      "recurring_tax_each": 0
    }
  ],
  "notes": null,
  "options": [
    {
      "id": "5becb84fac207653a4816ee5",
      "name": "Plan",
      "value": "Monthly"
    }
  ],
  "order_id": "5f626b0d91f0af999b00007b",
  "order_item_id": "5f626b0d91f0af999b00007c",
  "paid": true,
  "payment_balance": 0,
  "payment_total": 99,
  "price": 99,
  "price_total": 99,
  "product_discount_each": 0,
  "product_discount_total": 0,
  "product_discounts": null,
  "product_tax_each": 0,
  "product_tax_total": 0,
  "product_taxes": null,
  "quantity": 1,
  "recurring_discount_total": 0,
  "recurring_item_discount": 0,
  "recurring_item_tax": 0,
  "recurring_item_total": 0,
  "recurring_tax_included_total": 0,
  "recurring_tax_total": 0,
  "recurring_total": 99,
  "refund_total": 0,
  "status": "active",
  "sub_total": 148.8946,
  "tax_included_total": 0,
  "tax_total": 0,
  "taxes": null,
  "trial": false,
  "trial_days": 14,
  "unpaid": false,
  "variant_id": "5f626b0d91f0af999b00007d"
}

Subscribe a customer to a plan. When trial_days or date_trial_end are set, no invoices will be created, otherwise the customer's default billing card will be charged immediately. If the charge fails, this will return a validation error describing the failure and an invoice will not be created. If the charge succeeds, an invoice will be created and paid by the charge immediately.

Arguments

  • account_id required

    ID of the subscribed customer's account. This can't be changed.

  • product_id required

    ID of the subscription plan product. When changing the subscription product, the difference in price is prorated by adding a line item. The customer will be charged or credited the difference on their next invoice.

  • coupon_code optional

    Set to a valid coupon code to apply the coupon's discount. If the code is not found or invalid, a validation error is returned.

  • quantity optional

    Quantity of the plan to charge.

  • trial_days optional

    Set a number of days to offer a trial period. An invoice will not be issued until trial has elapsed.

  • Show all arguments
    • cancel_at_end optional

      Set true to make the subscription automatically become canceled at the end of the current billing period.

    • cancel_reason optional

      A brief message describing the reason the subscription was canceled, if applicable.

    • canceled optional

      Set true to cancel the subscription. If cancel_at_end is also set, the subscription will remain active until the end of the current billing period.

    • coupon_id optional

      ID of the coupon applied to the subscription.

    • currency optional

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

    • date_canceled optional

      Date the subscription was canceled, if applicable.

    • date_payment_failed optional

      Date when the last automated payment failed, if applicable.

    • date_trial_end optional

      Set a date the trial period should end. This value can be used to set the billing period of a subscription with or without a trial. For example, to set the monthly billing date to the 1st of the month, set date_trial_end to the 1st day of the next month.

    • interval_count optional

      Multiplier for billing interval. For example, to make the subscription charge once every 2 weeks, set interval=weekly and interval_count=2.

    • interval optional

      Billing interval. Can be monthly, daily, weekly or yearly.

    • items optional

      List of invoice line items added to the subscription. Recurring items are charged repeatedly, otherwise they are charged on the next invoice and then removed from the subscription.

      Show items arguments
      • items.description optional

        Description used for custom line items, when product is not defined.

      • items.options optional

        Item options matching one or more of product.options, if applicable. When setting this value, specify either option id or name (case-insensitive) to identify the option.

        Show options arguments
        • items.options.id optional

          Unique identifier for the object.

        • items.options.name optional

          Name of the option. Populated automatically when adding an option by ID.

        • items.options.price optional

          Price of the option added to plan price when selected.

        • items.options.value optional

          Name value of the option. When setting this value, specify either the product option value id or name (case-insensitive) to identify the value.

      • items.price optional

        Price of the line item. Defaults to product price, if applicable. A negative value will be subtracted from the plan total and credited to the customer on their next invoice.

      • items.product_id optional

        ID of the item product, if applicable.

      • items.quantity optional

        Quantity of the line item.

      • items.recurring optional

        Set true to make the item remain on the subscription after the next invoice is created.

      • items.variant_id optional

        ID of the item variant, if applicable.

    • notes optional

      Internal admin notes. These are not visible to the customer.

    • options optional

      Plan options matching one or more of product.options. When setting this value, specify either option id or name (case-insensitive) to identify the option.

      Show options arguments
      • options.id optional

        Unique identifier for the object.

      • options.name optional

        Name of the plan option. Populated automatically when adding an option by ID.

      • options.price optional

        Price of the option added to plan price when selected.

      • options.value optional

        Name value of the plan option. When setting this value, specify either value id or name (case-insensitive) to identify the value.

    • order_id optional

      ID of the order that originated the subscription, if applicable.

    • order_item_id optional

      ID of the line item from the order that originated the subscription, if applicable.

    • price optional

      Price of the plan. When updating price of an existing plan, the new price will be charged on the next invoice.

    • prorated optional

      Set false to indicate the subscription should not be prorated if the plan product is changed, otherwise a prorated charge or credit will be added at the appropriate time.

    • variant_id optional

      ID of the subscription plan variant, if applicable.

Returns

Returns a new subscription if valid arguments are provided, otherwise returns an object containing validation errors.

Retrieve a subscription

GET /subscriptions/:id

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


const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/subscriptions/{id}', {
  id: '5f626b0d91f0af999b00008a'
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->get('/subscriptions/{id}', [
  'id' => '5f626b0d91f0af999b00008a'
]);

Example response

{
  "id": "5f626b0d91f0af999b00008f",
  "account_id": "5f626b0d91f0af999b000090",
  "product_id": "5f626b0d91f0af999b000091",
  "active": true,
  "cancel_at_end": false,
  "cancel_reason": null,
  "canceled": false,
  "currency": "USD",
  "date_canceled": null,
  "date_created": "2020-09-16T19:44:13.840Z",
  "date_payment_expiring": "2031-01-01T08:00:00.000Z",
  "date_payment_failed": null,
  "date_payment_retry": null,
  "date_period_end": "2019-03-24T04:28:12.962Z",
  "date_period_start": "2019-02-24T04:28:12.962Z",
  "date_trial_end": "2019-02-24T04:28:12.962Z",
  "date_trial_start": "2019-01-24T04:28:12.962Z",
  "date_updated": "2020-09-16T19:44:13.840Z",
  "discount_total": 0,
  "discounts": null,
  "grand_total": 148.8946,
  "interval": "monthly",
  "interval_count": 1,
  "invoice_total": 99,
  "item_discount": 0,
  "item_tax": 0,
  "item_total": 49.8946,
  "items": [
    {
      "id": "5ca537326a0ec32a521139dd",
      "date_created": "2019-03-24T22:56:33.467Z",
      "description": "Remaining time on Example Subscription",
      "proration": true,
      "quantity": 1,
      "price": 49.8946,
      "price_total": 49.8946,
      "recurring_price": 0,
      "recurring_price_total": 0,
      "discount_total": 0,
      "discount_each": 0,
      "recurring_discount_total": 0,
      "recurring_discount_each": 0,
      "tax_total": 0,
      "tax_each": 0,
      "recurring_tax_total": 0,
      "recurring_tax_each": 0
    }
  ],
  "notes": null,
  "options": [
    {
      "id": "5becb84fac207653a4816ee5",
      "name": "Plan",
      "value": "Monthly"
    }
  ],
  "order_id": "5f626b0d91f0af999b00007b",
  "order_item_id": "5f626b0d91f0af999b00007c",
  "paid": true,
  "payment_balance": 0,
  "payment_total": 99,
  "price": 99,
  "price_total": 99,
  "product_discount_each": 0,
  "product_discount_total": 0,
  "product_discounts": null,
  "product_tax_each": 0,
  "product_tax_total": 0,
  "product_taxes": null,
  "quantity": 1,
  "recurring_discount_total": 0,
  "recurring_item_discount": 0,
  "recurring_item_tax": 0,
  "recurring_item_total": 0,
  "recurring_tax_included_total": 0,
  "recurring_tax_total": 0,
  "recurring_total": 99,
  "refund_total": 0,
  "status": "active",
  "sub_total": 148.8946,
  "tax_included_total": 0,
  "tax_total": 0,
  "taxes": null,
  "trial": false,
  "trial_days": 14,
  "unpaid": false,
  "variant_id": "5f626b0d91f0af999b00007d"
}

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

Arguments

  • id required

    ID of the subscription to retrieve.

  • expand optional

    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.

  • fields optional

    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 subscription id is always returned.

  • include optional

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

Returns

Returns a subscription if a valid ID was provided. Otherwise null.

Update a subscription

PUT /subscriptions/:id

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

  -X PUT
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.put('/subscriptions/{id}', {
  id: '5f626b0d91f0af999b000078'
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->put('/subscriptions/{id}', [
  'id' => '5f626b0d91f0af999b000078'
]);

Example response

{
  "id": "5f626b0d91f0af999b000078",
  "account_id": "5f626b0d91f0af999b000095",
  "product_id": "5f626b0d91f0af999b000096",
  "active": true,
  "cancel_at_end": false,
  "cancel_reason": null,
  "canceled": false,
  "currency": "USD",
  "date_canceled": null,
  "date_created": "2020-09-16T19:44:13.840Z",
  "date_payment_expiring": "2031-01-01T08:00:00.000Z",
  "date_payment_failed": null,
  "date_payment_retry": null,
  "date_period_end": "2019-03-24T04:28:12.962Z",
  "date_period_start": "2019-02-24T04:28:12.962Z",
  "date_trial_end": "2019-02-24T04:28:12.962Z",
  "date_trial_start": "2019-01-24T04:28:12.962Z",
  "date_updated": "2020-09-16T19:44:13.840Z",
  "discount_total": 0,
  "discounts": null,
  "grand_total": 148.8946,
  "interval": "monthly",
  "interval_count": 1,
  "invoice_total": 99,
  "item_discount": 0,
  "item_tax": 0,
  "item_total": 49.8946,
  "items": [
    {
      "id": "5ca537326a0ec32a521139dd",
      "date_created": "2019-03-24T22:56:33.467Z",
      "description": "Remaining time on Example Subscription",
      "proration": true,
      "quantity": 1,
      "price": 49.8946,
      "price_total": 49.8946,
      "recurring_price": 0,
      "recurring_price_total": 0,
      "discount_total": 0,
      "discount_each": 0,
      "recurring_discount_total": 0,
      "recurring_discount_each": 0,
      "tax_total": 0,
      "tax_each": 0,
      "recurring_tax_total": 0,
      "recurring_tax_each": 0
    }
  ],
  "notes": null,
  "options": [
    {
      "id": "5becb84fac207653a4816ee5",
      "name": "Plan",
      "value": "Monthly"
    }
  ],
  "order_id": "5f626b0d91f0af999b00007b",
  "order_item_id": "5f626b0d91f0af999b00007c",
  "paid": true,
  "payment_balance": 0,
  "payment_total": 99,
  "price": 99,
  "price_total": 99,
  "product_discount_each": 0,
  "product_discount_total": 0,
  "product_discounts": null,
  "product_tax_each": 0,
  "product_tax_total": 0,
  "product_taxes": null,
  "quantity": 1,
  "recurring_discount_total": 0,
  "recurring_item_discount": 0,
  "recurring_item_tax": 0,
  "recurring_item_total": 0,
  "recurring_tax_included_total": 0,
  "recurring_tax_total": 0,
  "recurring_total": 99,
  "refund_total": 0,
  "status": "active",
  "sub_total": 148.8946,
  "tax_included_total": 0,
  "tax_total": 0,
  "taxes": null,
  "trial": false,
  "trial_days": 14,
  "unpaid": false,
  "variant_id": "5f626b0d91f0af999b00007d"
}

Update an existing subscription 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

  • cancel_at_end optional

    Set true to make the subscription automatically become canceled at the end of the current billing period.

  • canceled optional

    Set true to cancel the subscription. If cancel_at_end is also set, the subscription will remain active until the end of the current billing period.

  • coupon_code optional

    Set to a valid coupon code to apply the coupon's discount. If the code is not found or invalid, a validation error is returned.

  • date_trial_end optional

    Set a date the trial period should end. This value can be used to set the billing period of a subscription with or without a trial. For example, to set the monthly billing date to the 1st of the month, set date_trial_end to the 1st day of the next month.

  • product_id optional

    ID of the subscription plan product. When changing the subscription product, the difference in price is prorated by adding a line item. The customer will be charged or credited the difference on their next invoice.

  • Show all arguments
    • cancel_reason optional

      A brief message describing the reason the subscription was canceled, if applicable.

    • coupon_id optional

      ID of the coupon applied to the subscription.

    • currency optional

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

    • date_canceled optional

      Date the subscription was canceled, if applicable.

    • date_payment_failed optional

      Date when the last automated payment failed, if applicable.

    • interval_count optional

      Multiplier for billing interval. For example, to make the subscription charge once every 2 weeks, set interval=weekly and interval_count=2.

    • interval optional

      Billing interval. Can be monthly, daily, weekly or yearly.

    • items optional

      List of invoice line items added to the subscription. Recurring items are charged repeatedly, otherwise they are charged on the next invoice and then removed from the subscription.

      Show items arguments
      • items.description optional

        Description used for custom line items, when product is not defined.

      • items.options optional

        Item options matching one or more of product.options, if applicable. When setting this value, specify either option id or name (case-insensitive) to identify the option.

        Show options arguments
        • items.options.id optional

          Unique identifier for the object.

        • items.options.name optional

          Name of the option. Populated automatically when adding an option by ID.

        • items.options.price optional

          Price of the option added to plan price when selected.

        • items.options.value optional

          Name value of the option. When setting this value, specify either the product option value id or name (case-insensitive) to identify the value.

      • items.price optional

        Price of the line item. Defaults to product price, if applicable. A negative value will be subtracted from the plan total and credited to the customer on their next invoice.

      • items.product_id optional

        ID of the item product, if applicable.

      • items.quantity optional

        Quantity of the line item.

      • items.recurring optional

        Set true to make the item remain on the subscription after the next invoice is created.

      • items.variant_id optional

        ID of the item variant, if applicable.

    • notes optional

      Internal admin notes. These are not visible to the customer.

    • options optional

      Plan options matching one or more of product.options. When setting this value, specify either option id or name (case-insensitive) to identify the option.

      Show options arguments
      • options.id optional

        Unique identifier for the object.

      • options.name optional

        Name of the plan option. Populated automatically when adding an option by ID.

      • options.price optional

        Price of the option added to plan price when selected.

      • options.value optional

        Name value of the plan option. When setting this value, specify either value id or name (case-insensitive) to identify the value.

    • order_id optional

      ID of the order that originated the subscription, if applicable.

    • order_item_id optional

      ID of the line item from the order that originated the subscription, if applicable.

    • price optional

      Price of the plan. When updating price of an existing plan, the new price will be charged on the next invoice.

    • prorated optional

      Set false to indicate the subscription should not be prorated if the plan product is changed, otherwise a prorated charge or credit will be added at the appropriate time.

    • quantity optional

      Quantity of the plan to charge.

    • trial_days optional

      Set a number of days to offer a trial period. An invoice will not be issued until trial has elapsed.

    • variant_id optional

      ID of the subscription plan variant, if applicable.

Returns

Returns the updated subscription if valid arguments are provided, otherwise returns an object containing validation errors.

List all subscriptions

GET /subscriptions

$ curl https://api.swell.store/subscriptions?limit=25&page=1 \
  -u store-id:secret-key \
  -G
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/subscriptions', {
  limit: 25,
  page: 1
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->get('/subscriptions', [
  'limit' => 25,
  'page' => 1
]);

Example response

{
  "count": 51,
  "results": [
    {
      "id": "5f626b0d91f0af999b000078",
      "account_id": "5f626b0d91f0af999b00009d",
      "product_id": "5f626b0d91f0af999b00009e",
      "active": true,
      "cancel_at_end": false,
      "cancel_reason": null,
      "canceled": false,
      "currency": "USD",
      "date_canceled": null,
      "date_created": "2020-09-16T19:44:13.840Z",
      "date_payment_expiring": "2031-01-01T08:00:00.000Z",
      "date_payment_failed": null,
      "date_payment_retry": null,
      "date_period_end": "2019-03-24T04:28:12.962Z",
      "date_period_start": "2019-02-24T04:28:12.962Z",
      "date_trial_end": "2019-02-24T04:28:12.962Z",
      "date_trial_start": "2019-01-24T04:28:12.962Z",
      "date_updated": "2020-09-16T19:44:13.840Z",
      "discount_total": 0,
      "discounts": null,
      "grand_total": 148.8946,
      "interval": "monthly",
      "interval_count": 1,
      "invoice_total": 99,
      "item_discount": 0,
      "item_tax": 0,
      "item_total": 49.8946,
      "items": [
        {
          "id": "5ca537326a0ec32a521139dd",
          "date_created": "2019-03-24T22:56:33.467Z",
          "description": "Remaining time on Example Subscription",
          "proration": true,
          "quantity": 1,
          "price": 49.8946,
          "price_total": 49.8946,
          "recurring_price": 0,
          "recurring_price_total": 0,
          "discount_total": 0,
          "discount_each": 0,
          "recurring_discount_total": 0,
          "recurring_discount_each": 0,
          "tax_total": 0,
          "tax_each": 0,
          "recurring_tax_total": 0,
          "recurring_tax_each": 0
        }
      ],
      "notes": null,
      "options": [
        {
          "id": "5becb84fac207653a4816ee5",
          "name": "Plan",
          "value": "Monthly"
        }
      ],
      "order_id": "5f626b0d91f0af999b00007b",
      "order_item_id": "5f626b0d91f0af999b00007c",
      "paid": true,
      "payment_balance": 0,
      "payment_total": 99,
      "price": 99,
      "price_total": 99,
      "product_discount_each": 0,
      "product_discount_total": 0,
      "product_discounts": null,
      "product_tax_each": 0,
      "product_tax_total": 0,
      "product_taxes": null,
      "quantity": 1,
      "recurring_discount_total": 0,
      "recurring_item_discount": 0,
      "recurring_item_tax": 0,
      "recurring_item_total": 0,
      "recurring_tax_included_total": 0,
      "recurring_tax_total": 0,
      "recurring_total": 99,
      "refund_total": 0,
      "status": "active",
      "sub_total": 148.8946,
      "tax_included_total": 0,
      "tax_total": 0,
      "taxes": null,
      "trial": false,
      "trial_days": 14,
      "unpaid": false,
      "variant_id": "5f626b0d91f0af999b00007d"
    },
    {...},
    {...}
  ],
  "page": 1,
  "pages": {
    "1": {
      "start": 1,
      "end": 25
    },
    "2": {
      "start": 26,
      "end": 50
    },
    "2": {
      "start": 51,
      "end": 51
    }
  }
}

Return a list of subscriptions.

Arguments

  • expand optional

    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.

  • fields optional

    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 subscription id is always returned.

  • include optional

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

  • limit optional

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

  • page optional

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

  • search optional

    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.

  • sort optional

    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.

  • where optional

    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.

Returns

An object with an array of results containing up to the limit and matching filters specified. If no records are found given the page and limit arguments, the results array will be empty. This request should never throw an error.

Delete a subscription

DELETE /subscriptions/:id

$ curl https://api.swell.store/subscriptions/5f626b0d91f0af999b0000a1 \
  -u store-id:secret-key \
  -X DELETE
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.delete('/subscriptions/{id}', {
  id: '5f626b0d91f0af999b0000a0'
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->delete('/subscriptions/{id}', [
  'id' => '5f626b0d91f0af999b0000a0'
]);

Example response

{
  "id": "5f626b0d91f0af999b0000a5",
  "account_id": "5f626b0d91f0af999b0000a6",
  "product_id": "5f626b0d91f0af999b0000a7",
  "active": true,
  "cancel_at_end": false,
  "cancel_reason": null,
  "canceled": false,
  "currency": "USD",
  "date_canceled": null,
  "date_created": "2020-09-16T19:44:13.840Z",
  "date_payment_expiring": "2031-01-01T08:00:00.000Z",
  "date_payment_failed": null,
  "date_payment_retry": null,
  "date_period_end": "2019-03-24T04:28:12.962Z",
  "date_period_start": "2019-02-24T04:28:12.962Z",
  "date_trial_end": "2019-02-24T04:28:12.962Z",
  "date_trial_start": "2019-01-24T04:28:12.962Z",
  "date_updated": "2020-09-16T19:44:13.840Z",
  "discount_total": 0,
  "discounts": null,
  "grand_total": 148.8946,
  "interval": "monthly",
  "interval_count": 1,
  "invoice_total": 99,
  "item_discount": 0,
  "item_tax": 0,
  "item_total": 49.8946,
  "items": [
    {
      "id": "5ca537326a0ec32a521139dd",
      "date_created": "2019-03-24T22:56:33.467Z",
      "description": "Remaining time on Example Subscription",
      "proration": true,
      "quantity": 1,
      "price": 49.8946,
      "price_total": 49.8946,
      "recurring_price": 0,
      "recurring_price_total": 0,
      "discount_total": 0,
      "discount_each": 0,
      "recurring_discount_total": 0,
      "recurring_discount_each": 0,
      "tax_total": 0,
      "tax_each": 0,
      "recurring_tax_total": 0,
      "recurring_tax_each": 0
    }
  ],
  "notes": null,
  "options": [
    {
      "id": "5becb84fac207653a4816ee5",
      "name": "Plan",
      "value": "Monthly"
    }
  ],
  "order_id": "5f626b0d91f0af999b00007b",
  "order_item_id": "5f626b0d91f0af999b00007c",
  "paid": true,
  "payment_balance": 0,
  "payment_total": 99,
  "price": 99,
  "price_total": 99,
  "product_discount_each": 0,
  "product_discount_total": 0,
  "product_discounts": null,
  "product_tax_each": 0,
  "product_tax_total": 0,
  "product_taxes": null,
  "quantity": 1,
  "recurring_discount_total": 0,
  "recurring_item_discount": 0,
  "recurring_item_tax": 0,
  "recurring_item_total": 0,
  "recurring_tax_included_total": 0,
  "recurring_tax_total": 0,
  "recurring_total": 99,
  "refund_total": 0,
  "status": "active",
  "sub_total": 148.8946,
  "tax_included_total": 0,
  "tax_total": 0,
  "taxes": null,
  "trial": false,
  "trial_days": 14,
  "unpaid": false,
  "variant_id": "5f626b0d91f0af999b00007d"
}

Delete a subscription permanently.

Arguments

  • id required

    ID of the subscription to delete.

Returns

Returns the original subscription if the operation was successful, or null if the subscription was not found.

Subscription plans

Subscription plans are products with type=subscription. When creating a plan, consider whether it's needed to ship physical items or not.

Create a digital subscription plan

POST /products

$ curl https://api.swell.store/products \
  -u store-id:secret-key \
  -d name="Pro plan" \
  -d type=subscription \
  -d options[0][name]=Plan \
  -d options[0][variant]=true \
  -d options[0][subscription]=true \
  -d options[0][values][0][name]=Monthly \
  -d options[0][values][0][price]=99 \
  -d options[0][values][0][subscription_interval]=monthly \
  -d options[0][values][1][name]=Yearly \
  -d options[0][values][1][price]=999 \
  -d options[0][values][1][subscription_interval]=yearly
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.post('/products', {
  name: 'Pro plan',
  type: 'subscription',
  options: [
    {
      name: 'Plan',
      variant: true,
      subscription: true,
      values: [
        {
          name: 'Monthly',
          subscription_interval: 'monthly',
          price: 99,
        },
        {
          name: 'Yearly',
          subscription_interval: 'yearly',
          price: 999,
        },
      ],
    },
  ],
});
<?php $swell = new \Swell\Client('store-id', 'secret-key');

$swell->post('/orders', [
  'name' => 'Pro plan',
  'type' => 'subscription',
  'options' => [
    [
      'name' => 'Plan',
      'variant' => true,
      'subscription' => true,
      'values' => [
        [
          'name' => 'Monthly',
          'subscription_interval' => 'monthly',
          'price' => 99
        ],
        [
          'name' => 'Yearly',
          'subscription_interval' => 'yearly',
          'price' => 999
        ]
      ]
    ]
  ]
]);

Example response

{
  "id": "5cad15bc9b14d1990724663a",
  "delivery": "subscription"
  "name": "Pro plan",
  "options": [
    {
      "id": "5ca24ab32599d4179c24a624",
      "name": "Plan",
      "variant": true,
      "subscription": true,
      "values": [
        {
          "id": "5ca24ad59c077817e5fe2ba3",
          "name": "Monthly",
          "subscription_interval": "monthly",
          "price": 99
        },
        {
          "id": "5ca24ad59c077817e5fe2ba4",
          "name": "Yearly",
          "subscription_interval": "yearly",
          "price": 999
        }
      ]
    }
  ],
  "slug": "pro-plan",
  "type": "subscription"
}

Create a subscription plan without physical items.

Arguments

  • name required

    Human-friendly name of the product.

  • options required

    Specify the billing options available on the plan.

    Show options arguments
    • options.name required

      Name of the billing option.

    • options.subscription required

      Must be true for subscription options.

    • options.values required

      List of possible values for this option.

      Show values arguments
      • options.values.name required

        Human-friendly name of the option value.

      • options.values.price required

        Price used when the option is selected.

      • options.values.subscription_interval required

        Set the billing interval used when this option is selected. Can be monthly, yearly, weekly or daily.

      • options.values.subscription_interval_count optional

        This number multiplies subscription_interval to determine the billing frequency when this option is selected. For example, to make a subscription bill every 2 weeks, set subscription_interval=weekly and subscription_interval_count=2. Defaults to 1.

      • options.values.subscription_trial_days optional

        A number of days offered as a trial before an invoice is issued.

    • options.variant required

      Must be true for subscription options.

  • type required

    Set to subscription to indicate the product is a subscription plan.

  • Show all arguments
    • active optional

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

    • attributes optional

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

    • category_id optional

      Primary category, commonly used as a navigation anchor.

    • description optional

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

    • images optional

      List of images depicting the bundle.

      Show images arguments
      • images.caption optional

        A brief description of the image, intended for display as a caption or alt text.

      • images.file optional

        An object representing the image's source file.

        Show file arguments
        • images.file.data optional

          Set or overwrite file data. Use the following format when writing a file from binary data (for example an image): data[$binary]=<base64 encoded binary daya>.

        • images.file.filename optional

          Optional file name.

    • meta_description optional

      Page description used for search engine optimization purposes.

    • meta_keywords optional

      Page keywords used for search engine optimization purposes.

    • meta_title optional

      Page title used to override product name in storefronts.

    • slug optional

      Lowercase, hyphenated identifier typically used in URLs. When creating a product, a slug will be generated automatically from the name.

    • tags optional

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

Returns

Returns a new product if valid arguments are provided, otherwise returns an object containing validation errors.

Create a plan with physical items

POST /products

$ curl https://api.swell.store/products \
  -u store-id:secret-key \
  -d name="Coffee club" \
  -d type=subscription \
  -d bundle_items[0][product_id]=5ca24abb9c077817e5fe2b36 \
  -d bundle_items[0][quantity]=1 \
  -d options[0][name]=Plan \
  -d options[0][variant]=true \
  -d options[0][subscription]=true \
  -d options[0][values][0][name]=Weekly \
  -d options[0][values][0][price]=15 \
  -d options[0][values][0][subscription_interval]=weekly \
  -d options[0][values][1][name]=Monthly \
  -d options[0][values][1][price]=19 \
  -d options[0][values][1][subscription_interval]=monthly \
const swell = require('swell-node').init('store-id', 'secret-key');

await swell.post('/products', {
  name: 'Coffee club',
  type: 'subscription',
  bundle_items: [
    {
      product_id: '5ca24abb9c077817e5fe2b36',
      quantity: 1
    }
  ],
  options: [
    {
      name: 'Plan',
      variant: true,
      subscription: true,
      values: [
        {
          name: 'Weekly',
          subscription_interval: 'weekly',
          price: 15,
        },
        {
          name: 'Monthly',
          subscription_interval: 'monthly',
          price: 19,
        },
      ],
    },