Products - Rutter API Reference - the Common Language for Business Data

The Product object

A Rutter Product represents a product contained in a merchant's catalog. Every product contains variants, which represent the different types or options of products sold (e.g. size, color, model). The product object contains high level information about the item including name, images, and tags, whereas the variant object contains physical information about the item, including price and weight.

In the case where a product in a merchant's catalog contains no variants, a default variant will exist containing information about the product.

Properties

idstring

The Rutter generated unique ID of the product.

platform_idstringoptional

The platform specific ID of the product.

descriptionstring

The description of the product.

namestring

The name of the product.

typestring

The unstandardized type or categorization of the product.

product_urlstringoptional

The consumer facing URL used to access the product online.

imagesarray

An array of images linked to the product.

Show images attributes

status

The status of the product.

tagsarray

An array of tags linked to the product.

String array.

variantsarray

An array of Variants linked to the product.

Show variants attributes

created_atstring

The ISO 8601 timestamp that the product was created.

updated_atstring

The ISO 8601 timestamp that the product was last updated.

Example Product Object

{
  "id": "00000000-0000-0000-0000-000000000000",
  "platform_id": "12345678",
  "description": "A Rutter Shirt. It comes in all shapes and sizes.",
  "name": "Rutter shirt",
  "type": "physical",
  "product_url": "https://rutter.com/products/shirt",
  "images": [
    {
      "src": "https://rutter.com/products/shirtlarge.jpg"
    },
    {
      "src": "https://rutter.com/products/shirt.jpg"
    },
    {
      "src": "https://rutter.com/products/shirtsmall.jpg"
    }
  ],
  "status": "active",
  "tags": [
    "clothing",
    "shirt"
  ],
  "variants": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "platform_id": "12345678",
      "product_id": "00000000-0000-0000-0000-000000000000",
      "price": 12.34,
      "requires_shipping": true,
      "barcode": "0012345678901",
      "fulfillment_service": "fedex",
      "inventory_management": "shopify",
      "iso_currency_code": "USD",
      "sku": "RUTTER-1",
      "title": "Rutter shirt (Large)",
      "unit_cost": 12.34,
      "variant_url": "https://rutter.com/products/shirt?size=large",
      "description": "A Rutter Shirt. It comes in all shapes and sizes, but this one is large",
      "images": [
        {
          "src": "https://rutter.com/products/shirtlarge.jpg"
        }
      ],
      "short_description": "Rutter shirt (Large)",
      "option_values": [
        {
          "name": "size",
          "value": "large"
        }
      ],
      "currency_prices": [
        {
          "iso_currency_code": "USD",
          "price": 12.34
        }
      ],
      "weight": {
        "unit": "kg",
        "value": 10
      },
      "linked_products": [
        {
          "variant_id": "00000000-0000-0000-0000-000000000000",
          "link_type": "product",
          "sku": "RUTTER-2"
        }
      ],
      "inventory": {
        "total_count": 10,
        "locations": []
      },
      "created_at": "2023-01-02T02:34:56.000Z",
      "updated_at": "2023-01-02T02:34:56.000Z"
    }
  ],
  "created_at": "2023-01-02T02:34:56.000Z",
  "updated_at": "2023-01-02T02:34:56.000Z"
}

List Products

GET /versioned/products

Supported for: AmazonBig CommerceeBayEtsyLazadaMagentoMercado LibrePrestashopShopifySquareSquarespaceWalmartWixWoo Commerce

Request Parameters

access_tokenstringquery

The access token of the connection.

created_at_maxintegeroptionalquery

Unix Timestamp in milliseconds representing the maximum created_at datetime to fetch entities from.

created_at_minintegeroptionalquery

Unix Timestamp in milliseconds representing the minimum created_at datetime to fetch entities from.

cursorstringoptionalquery

The cursor to use for pagination. This value is passed in from next_cursor field in a previous request.

force_fetchenumoptionalquery

Force a response even if the underlying connection hasn't finished the initial sync.

One oftrue or false.

limitintegeroptionalquery

The limit on the number of entities returned.

namestringoptionalquery

Filter products by names similar to the input.

statusenumoptionalquery

Show products with certain product status.

One ofactive, archived, inactive, or draft.

updated_at_maxintegeroptionalquery

Unix Timestamp in milliseconds representing the maximum updated_at datetime to fetch entities from.

updated_at_minintegeroptionalquery

Unix Timestamp in milliseconds representing the minimum updated_at datetime to fetch entities from.

Response Body

connectionobject

Show connection attributes

productsarray

Show products attributes

next_cursorstringnullable

Example Response Body

{
  "connection": {
    "id": "00000000-0000-0000-0000-000000000000",
    "orgId": "00000000-0000-0000-0000-000000000000",
    "platform": "SHOPIFY"
  },
  "products": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "platform_id": "12345678",
      "description": "A Rutter Shirt. It comes in all shapes and sizes.",
      "name": "Rutter shirt",
      "type": "physical",
      "product_url": "https://rutter.com/products/shirt",
      "images": [
        {
          "src": "https://rutter.com/products/shirtlarge.jpg"
        },
        {
          "src": "https://rutter.com/products/shirt.jpg"
        },
        {
          "src": "https://rutter.com/products/shirtsmall.jpg"
        }
      ],
      "status": "active",
      "tags": [
        "clothing",
        "shirt"
      ],
      "variants": [
        {
          "id": "00000000-0000-0000-0000-000000000000",
          "platform_id": "12345678",
          "product_id": "00000000-0000-0000-0000-000000000000",
          "price": 12.34,
          "requires_shipping": true,
          "barcode": "0012345678901",
          "fulfillment_service": "fedex",
          "inventory_management": "shopify",
          "iso_currency_code": "USD",
          "sku": "RUTTER-1",
          "title": "Rutter shirt (Large)",
          "unit_cost": 12.34,
          "variant_url": "https://rutter.com/products/shirt?size=large",
          "description": "A Rutter Shirt. It comes in all shapes and sizes, but this one is large",
          "images": [
            {
              "src": "https://rutter.com/products/shirtlarge.jpg"
            }
          ],
          "short_description": "Rutter shirt (Large)",
          "option_values": [
            {
              "name": "size",
              "value": "large"
            }
          ],
          "currency_prices": [
            {
              "iso_currency_code": "USD",
              "price": 12.34
            }
          ],
          "weight": {
            "unit": "kg",
            "value": 10
          },
          "linked_products": [
            {
              "variant_id": "00000000-0000-0000-0000-000000000000",
              "link_type": "product",
              "sku": "RUTTER-2"
            }
          ],
          "inventory": {
            "total_count": 10,
            "locations": []
          },
          "created_at": "2023-01-02T02:34:56.000Z",
          "updated_at": "2023-01-02T02:34:56.000Z"
        }
      ],
      "created_at": "2023-01-02T02:34:56.000Z",
      "updated_at": "2023-01-02T02:34:56.000Z"
    }
  ],
  "next_cursor": "MTY3NDgzMTk0Ml82MDY4ZDI0ZC02NGRmLTRmN2EtYTM0Ny0zN2ZmNjY5MGVmMjU="
}

Fetch a Product

GET /versioned/products/:id

Supported for: AmazonBig CommerceeBayEtsyMagentoMercado LibrePrestashopShopifySquareSquarespaceWixWoo Commerce

Request Parameters

idstringpath

The Rutter generated unique ID of the object.

access_tokenstringquery

The access token of the connection.

force_fetchenumoptionalquery

Force a response even if the underlying connection hasn't finished the initial sync.

One oftrue or false.

Response Body

connectionobject

Show connection attributes

productobject

Show product attributes

Example Response Body

{
  "connection": {
    "id": "00000000-0000-0000-0000-000000000000",
    "orgId": "00000000-0000-0000-0000-000000000000",
    "platform": "SHOPIFY"
  },
  "product": {
    "id": "00000000-0000-0000-0000-000000000000",
    "platform_id": "12345678",
    "description": "A Rutter Shirt. It comes in all shapes and sizes.",
    "name": "Rutter shirt",
    "type": "physical",
    "product_url": "https://rutter.com/products/shirt",
    "images": [
      {
        "src": "https://rutter.com/products/shirtlarge.jpg"
      },
      {
        "src": "https://rutter.com/products/shirt.jpg"
      },
      {
        "src": "https://rutter.com/products/shirtsmall.jpg"
      }
    ],
    "status": "active",
    "tags": [
      "clothing",
      "shirt"
    ],
    "variants": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "platform_id": "12345678",
        "product_id": "00000000-0000-0000-0000-000000000000",
        "price": 12.34,
        "requires_shipping": true,
        "barcode": "0012345678901",
        "fulfillment_service": "fedex",
        "inventory_management": "shopify",
        "iso_currency_code": "USD",
        "sku": "RUTTER-1",
        "title": "Rutter shirt (Large)",
        "unit_cost": 12.34,
        "variant_url": "https://rutter.com/products/shirt?size=large",
        "description": "A Rutter Shirt. It comes in all shapes and sizes, but this one is large",
        "images": [
          {
            "src": "https://rutter.com/products/shirtlarge.jpg"
          }
        ],
        "short_description": "Rutter shirt (Large)",
        "option_values": [
          {
            "name": "size",
            "value": "large"
          }
        ],
        "currency_prices": [
          {
            "iso_currency_code": "USD",
            "price": 12.34
          }
        ],
        "weight": {
          "unit": "kg",
          "value": 10
        },
        "linked_products": [
          {
            "variant_id": "00000000-0000-0000-0000-000000000000",
            "link_type": "product",
            "sku": "RUTTER-2"
          }
        ],
        "inventory": {
          "total_count": 10,
          "locations": []
        },
        "created_at": "2023-01-02T02:34:56.000Z",
        "updated_at": "2023-01-02T02:34:56.000Z"
      }
    ],
    "created_at": "2023-01-02T02:34:56.000Z",
    "updated_at": "2023-01-02T02:34:56.000Z"
  }
}

List Product Categories

GET /versioned/products/categories

Supported for: AmazonBig CommerceEtsyMagentoShopify

Request Parameters

access_tokenstringquery

The access token of the connection.

force_fetchenumoptionalquery

Force a response even if the underlying connection hasn't finished the initial sync.

One oftrue or false.

idstringoptionalquery

Only fetch a specific product category id.

Response Body

categoriesarray

Show categories attributes

Example Response Body

{
  "categories": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "Shirts",
      "children": [
        {
          "id": "00000000-0000-0000-0000-000000000000",
          "name": "T Shirts",
          "children": []
        },
        {
          "id": "00000000-0000-0000-0000-000000000000",
          "name": "Long sleeve shirts",
          "children": []
        }
      ]
    }
  ]
}

Create a Product

POST /versioned/products

Supported for: AmazonBig CommerceEtsyMagentoPrestashopShopifySquareSquarespaceWixWoo Commerce

Request Parameters

access_tokenstringquery

The access token of the connection.

Request Body

productobject

Show product attributes

Response Body

Any of:

async_responseobject

Show async_response attributes

productobject

Show product attributes

Example Request Body

{
  "product": {
    "category_id": 123456789,
    "description": "A Rutter Shirt. It comes in all shapes and sizes.",
    "name": "Rutter shirt",
    "status": "active",
    "tags": [
      "clothing",
      "shirt"
    ],
    "images": [
      {
        "src": "https://rutter.com/products/shirtlarge.jpg"
      },
      {
        "src": "https://rutter.com/products/shirt.jpg"
      },
      {
        "src": "https://rutter.com/products/shirtsmall.jpg"
      }
    ],
    "variants": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "price": 12.34,
        "sku": "RUTTER-1",
        "images": [
          {
            "src": "https://rutter.com/products/shirtlarge.jpg"
          }
        ],
        "option_values": [
          {
            "name": "size",
            "value": "large"
          }
        ],
        "weight": {
          "unit": "kg",
          "value": 10
        },
        "inventory": {
          "total_count": 10
        }
      }
    ],
    "additional_fields": {
      "amazon": {
        "sku": "RUTTER-1",
        "display_album": null,
        "decorative_cutout": null,
        "cellular_phone_case": null,
        "wall_art": null,
        "drinking_cup": null,
        "tote_bag": null,
        "shirt": null,
        "sweatshirt": null
      }
    }
  }
}

Example Response Body

{
  "product": {
    "id": "00000000-0000-0000-0000-000000000000",
    "platform_id": "12345678",
    "description": "A Rutter Shirt. It comes in all shapes and sizes.",
    "name": "Rutter shirt",
    "type": "physical",
    "product_url": "https://rutter.com/products/shirt",
    "images": [
      {
        "src": "https://rutter.com/products/shirtlarge.jpg"
      },
      {
        "src": "https://rutter.com/products/shirt.jpg"
      },
      {
        "src": "https://rutter.com/products/shirtsmall.jpg"
      }
    ],
    "status": "active",
    "tags": [
      "clothing",
      "shirt"
    ],
    "variants": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "platform_id": "12345678",
        "product_id": "00000000-0000-0000-0000-000000000000",
        "price": 12.34,
        "requires_shipping": true,
        "barcode": "0012345678901",
        "fulfillment_service": "fedex",
        "inventory_management": "shopify",
        "iso_currency_code": "USD",
        "sku": "RUTTER-1",
        "title": "Rutter shirt (Large)",
        "unit_cost": 12.34,
        "variant_url": "https://rutter.com/products/shirt?size=large",
        "description": "A Rutter Shirt. It comes in all shapes and sizes, but this one is large",
        "images": [
          {
            "src": "https://rutter.com/products/shirtlarge.jpg"
          }
        ],
        "short_description": "Rutter shirt (Large)",
        "option_values": [
          {
            "name": "size",
            "value": "large"
          }
        ],
        "currency_prices": [
          {
            "iso_currency_code": "USD",
            "price": 12.34
          }
        ],
        "weight": {
          "unit": "kg",
          "value": 10
        },
        "linked_products": [
          {
            "variant_id": "00000000-0000-0000-0000-000000000000",
            "link_type": "product",
            "sku": "RUTTER-2"
          }
        ],
        "inventory": {
          "total_count": 10,
          "locations": []
        },
        "created_at": "2023-01-02T02:34:56.000Z",
        "updated_at": "2023-01-02T02:34:56.000Z"
      }
    ],
    "created_at": "2023-01-02T02:34:56.000Z",
    "updated_at": "2023-01-02T02:34:56.000Z"
  }
}

Update a Product

PATCH /versioned/products/:id

Supported for: Big CommerceEtsyMagentoPrestashopShopifySquareSquarespaceWixWoo Commerce

Request Parameters

idstringpath

The Rutter generated unique ID of the object.

access_tokenstringquery

The access token of the connection.

Request Body

productobject

Show product attributes

Response Body

productobject

Show product attributes

Example Request Body

{
  "product": {
    "description": "A Rutter Shirt. It comes in all shapes and sizes.",
    "name": "Rutter shirt",
    "status": "active"
  }
}

Example Response Body

{
  "product": {
    "id": "00000000-0000-0000-0000-000000000000",
    "platform_id": "12345678",
    "description": "A Rutter Shirt. It comes in all shapes and sizes.",
    "name": "Rutter shirt",
    "type": "physical",
    "product_url": "https://rutter.com/products/shirt",
    "images": [
      {
        "src": "https://rutter.com/products/shirtlarge.jpg"
      },
      {
        "src": "https://rutter.com/products/shirt.jpg"
      },
      {
        "src": "https://rutter.com/products/shirtsmall.jpg"
      }
    ],
    "status": "active",
    "tags": [
      "clothing",
      "shirt"
    ],
    "variants": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "platform_id": "12345678",
        "product_id": "00000000-0000-0000-0000-000000000000",
        "price": 12.34,
        "requires_shipping": true,
        "barcode": "0012345678901",
        "fulfillment_service": "fedex",
        "inventory_management": "shopify",
        "iso_currency_code": "USD",
        "sku": "RUTTER-1",
        "title": "Rutter shirt (Large)",
        "unit_cost": 12.34,
        "variant_url": "https://rutter.com/products/shirt?size=large",
        "description": "A Rutter Shirt. It comes in all shapes and sizes, but this one is large",
        "images": [
          {
            "src": "https://rutter.com/products/shirtlarge.jpg"
          }
        ],
        "short_description": "Rutter shirt (Large)",
        "option_values": [
          {
            "name": "size",
            "value": "large"
          }
        ],
        "currency_prices": [
          {
            "iso_currency_code": "USD",
            "price": 12.34
          }
        ],
        "weight": {
          "unit": "kg",
          "value": 10
        },
        "linked_products": [
          {
            "variant_id": "00000000-0000-0000-0000-000000000000",
            "link_type": "product",
            "sku": "RUTTER-2"
          }
        ],
        "inventory": {
          "total_count": 10,
          "locations": []
        },
        "created_at": "2023-01-02T02:34:56.000Z",
        "updated_at": "2023-01-02T02:34:56.000Z"
      }
    ],
    "created_at": "2023-01-02T02:34:56.000Z",
    "updated_at": "2023-01-02T02:34:56.000Z"
  }
}

Delete a Product

DELETE /versioned/products/:id

Supported for: Big CommerceEtsyMagentoPrestashopShopifySquareSquarespaceWixWoo Commerce

Request Parameters

idstringpath

The Rutter generated unique ID of the object.

access_tokenstringquery

The access token of the connection.

Response Body

productstring

Id of the deleted product

successboolean

true if the delete operation succeeded.

Example Response Body

{
  "product": "00000000-0000-0000-0000-000000000000",
  "success": true
}

Create a Product Variant

POST /versioned/products/:id/variants

Supported for: Big CommerceEtsyMagentoPrestashopShopifySquareSquarespaceWixWoo Commerce

Request Parameters

access_tokenstringquery

The access token of the connection.

Request Body

variantobject

Show variant attributes

Response Body

variantobject

Show variant attributes

Example Request Body

{
  "variant": {
    "id": "00000000-0000-0000-0000-000000000000",
    "price": 12.34,
    "sku": "RUTTER-1",
    "images": [
      {
        "src": "https://rutter.com/products/shirtlarge.jpg"
      }
    ],
    "option_values": [
      {
        "name": "size",
        "value": "large"
      }
    ],
    "weight": {
      "unit": "kg",
      "value": 10
    },
    "inventory": {
      "total_count": 10
    }
  }
}

Example Response Body

{
  "variant": {
    "id": "00000000-0000-0000-0000-000000000000",
    "platform_id": "12345678",
    "product_id": "00000000-0000-0000-0000-000000000000",
    "price": 12.34,
    "requires_shipping": true,
    "barcode": "0012345678901",
    "fulfillment_service": "fedex",
    "inventory_management": "shopify",
    "iso_currency_code": "USD",
    "sku": "RUTTER-1",
    "title": "Rutter shirt (Large)",
    "unit_cost": 12.34,
    "variant_url": "https://rutter.com/products/shirt?size=large",
    "description": "A Rutter Shirt. It comes in all shapes and sizes, but this one is large",
    "images": [
      {
        "src": "https://rutter.com/products/shirtlarge.jpg"
      }
    ],
    "short_description": "Rutter shirt (Large)",
    "option_values": [
      {
        "name": "size",
        "value": "large"
      }
    ],
    "currency_prices": [
      {
        "iso_currency_code": "USD",
        "price": 12.34
      }
    ],
    "weight": {
      "unit": "kg",
      "value": 10
    },
    "linked_products": [
      {
        "variant_id": "00000000-0000-0000-0000-000000000000",
        "link_type": "product",
        "sku": "RUTTER-2"
      }
    ],
    "inventory": {
      "total_count": 10,
      "locations": []
    },
    "created_at": "2023-01-02T02:34:56.000Z",
    "updated_at": "2023-01-02T02:34:56.000Z"
  }
}

Update a Product Variant

PATCH /versioned/products/:id/variants/:variantId

Supported for: Big CommerceEtsyMagentoPrestashopShopifySquareSquarespaceWixWoo Commerce

Request Parameters

variantIdstringpath

The Rutter generated unique ID of the variant.

access_tokenstringquery

The access token of the connection.

Request Body

variantobject

Show variant attributes

Response Body

variantobject

Show variant attributes

Example Request Body

{
  "variant": {
    "id": "00000000-0000-0000-0000-000000000000",
    "price": 12.34,
    "sku": "RUTTER-1",
    "images": [
      {
        "src": "https://rutter.com/products/shirtlarge.jpg"
      }
    ],
    "weight": {
      "unit": "kg",
      "value": 10
    },
    "option_values": [
      {
        "name": "size",
        "value": "large"
      }
    ],
    "inventory": {
      "total_count": 10
    }
  }
}

Example Response Body

{
  "variant": {
    "id": "00000000-0000-0000-0000-000000000000",
    "platform_id": "12345678",
    "product_id": "00000000-0000-0000-0000-000000000000",
    "price": 12.34,
    "requires_shipping": true,
    "barcode": "0012345678901",
    "fulfillment_service": "fedex",
    "inventory_management": "shopify",
    "iso_currency_code": "USD",
    "sku": "RUTTER-1",
    "title": "Rutter shirt (Large)",
    "unit_cost": 12.34,
    "variant_url": "https://rutter.com/products/shirt?size=large",
    "description": "A Rutter Shirt. It comes in all shapes and sizes, but this one is large",
    "images": [
      {
        "src": "https://rutter.com/products/shirtlarge.jpg"
      }
    ],
    "short_description": "Rutter shirt (Large)",
    "option_values": [
      {
        "name": "size",
        "value": "large"
      }
    ],
    "currency_prices": [
      {
        "iso_currency_code": "USD",
        "price": 12.34
      }
    ],
    "weight": {
      "unit": "kg",
      "value": 10
    },
    "linked_products": [
      {
        "variant_id": "00000000-0000-0000-0000-000000000000",
        "link_type": "product",
        "sku": "RUTTER-2"
      }
    ],
    "inventory": {
      "total_count": 10,
      "locations": []
    },
    "created_at": "2023-01-02T02:34:56.000Z",
    "updated_at": "2023-01-02T02:34:56.000Z"
  }
}

Delete a Product Variant

DELETE /versioned/products/:id/variants/:id

Supported for: Big CommerceEtsyShopifySquarespaceWixWoo Commerce

Request Parameters

idstringpath

The Rutter generated unique ID of the variant.

access_tokenstringquery

The access token of the connection.

Response Body

productIdstring

variantIdstring

Example Response Body

{
  "productId": "00000000-0000-0000-0000-000000000000",
  "variantId": "00000000-0000-0000-0000-000000000000"
}