SellApp

Products

Products are objects containing variants. When a customer purchases a product, they are sent the respetive deliverable(s) that product's variant contains.

One product can have many variants, each of which have their own price, product deliverable, and pricing.

On this page, we'll dive into the different product endpoints you can use to manage products - and product variants - programmatically. We'll look at how to create, update, and delete products.

The product model

The product model contains all the information about the products stores have, including the price, media, and customization options.

Properties

  • Name
    id
    Type
    integer
    Description

    The unique product identifier

  • Name
    title
    Type
    string
    Description

    The product title.

  • Name
    slug
    Type
    string
    Description

    The unique product slug.

  • Name
    description
    Type
    string
    Description

    The product description.

  • Name
    images
    Type
    object
    Description

    The array of product images, displays the following information:

    • path image path
    • metadata array of image metadata
      • size size in bytes
      • filename file name
      • extension file extension
      • mime_type file mime type
  • Name
    order
    Type
    integer
    Description

    The order of the product relative to all other products in your storefront.

  • Name
    visibility
    Type
    string
    Description

    The product visibility. One of four values:

    • PUBLIC Product can be visited and purchased.
    • ON_HOLD Product can be visited but not be purchased.
    • HIDDEN Product can be only visited via direct link and purchased.
    • PRIVATE Product cannot be visited nor purchased.
  • Name
    delivery_text
    Type
    string
    Description

    The product delivery text, shown to customers in addition to the variant deliverables. Useful as a thank you note or offering a discount.

  • Name
    additional_information
    Type
    array
    Description

    The additional information input(s) of the product. Array consists of:

    • required Boolean which pecifies whether the additional information is required
    • key Unique additional information key, this is used when creating an invoice
    • type One of five values:
      • TEXT
      • NUMBER
      • HIDDEN
      • TEXTAREA
      • CHECKBOX
    • label The name of the additional information input. Examples:
      • TEXT "What is your in-game username?"
      • NUMBER "Enter your mobile number on which you'd like to receive this top-up"
      • HIDDEN n.a. (as this is a hidden input not visible to the end-user)
      • TEXTAREA "Tell us in detail how you'd like your website to be customized"
      • CHECKBOX "Do you agree to my terms of service?"
  • Name
    other_settings
    Type
    array
    Description

    Customization settings of the product, with the following options:

    • faq Object containing an array of frequently asked questions to be displayed on the product page. Consists of:
      • question FAQ question.
      • answer FAQ answer.
    • video_url URL of a product video, will be displayed on the product page. Supported services: YouTube, Vimeo, Dailymotion, Slideshare, Miro
    • redirect_url URL you want to redirect your customers to after a successful purchase. The redirect URL can utilize the following dynamic values:
      • [order_id] ID of the order
      • [customer_email] email of the customer who placed the order
    • product_title Meta title tag of the product, will appear in search engines and social media.
    • product_description Meta description tag of the product, will appear in search engines and social media.
  • Name
    deleted_at
    Type
    timestamp
    Description

    The time at which this product was deleted.

  • Name
    created_at
    Type
    timestamp
    Description

    The time at which this product was first created.

  • Name
    updated_at
    Type
    timestamp
    Description

    The time at which this product was last updated.

  • Name
    store_id
    Type
    integer
    Description

    The ID of the store this product belongs to.

  • Name
    category_id
    Type
    integer
    Description

    The ID of the category this product belongs to.

  • Name
    section_id
    Type
    integer
    Description

    The ID of the section this product belongs to.

  • Name
    section_order
    Type
    integer
    Description

    The order of the product within the section.

  • Name
    is_discoverable
    Type
    integer
    Description

    Whether the product can be discovered. One of two values:

    • 1 It can be discovered.
    • 0 It cannot be discovered.
  • Name
    variants
    Type
    object
    Description

    Variants object containing a number of variant arrays. Variant arrays consist of:

    • id Variant ID
    • title Variant title
  • Name
    url
    Type
    string
    Description

    Displays the full product URL, including storefront domain.

GET/v2/products

List all products

This endpoint allows you to retrieve a paginated list of all your products. By default, a maximum of fifteen products are shown per page.

Optional attributes

  • Name
    limit
    Type
    integer
    Description

    Limit the number of products returned

  • Name
    page
    Type
    integer
    Description

    The page number you are attempting to access.

  • Name
    with_trashed
    Type
    boolean
    Description

    Include deleted products in the results

  • Name
    only_trashed
    Type
    boolean
    Description

    Limit the results to only deleted products

Request

GET
/v2/products
$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://sell.app/api/v2/products');
$request->setRequestMethod('GET');
$request->setHeaders([
  'accept' => 'application/json',
  'Authorization' => 'Bearer {ApiKeyHere}'
]);

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

Response

{
  "data": [
    {
      "id": 1,
      "title": "Elixir of immortality",
      "slug": "elixir-of-immortality",
      "description": "<p>Want to live forever? Buy this now and I'll send a digital elixir that converts your soul into an NFT that will roam the internet for eternity!<\/p>",
      "images": [
        {
          "path": "store\/1\/listings\/NM6TBKIMzpFJq1MKTV24oMJ1W4UrKCo7NS98nt4K.png",
          "metadata": {
            "size": 39289,
            "filename": "NM6TBKIMzpFJq1MKTV24oMJ1W4UrKCo7NS98nt4K",
            "extension": "png",
            "mime_type": "image\/png"
          }
        },
        {
          "path": "store\/1\/listings\/ov6XMb68tRr80zl7sqfN1or7xfqqH5WbZygDEQ8X.png",
          "metadata": {
            "size": 422373,
            "filename": "ov6XMb68tRr80zl7sqfN1or7xfqqH5WbZygDEQ8X",
            "extension": "png",
            "mime_type": "image\/png"
          }
        }
      ],
      "order": 1,
      "visibility": "PUBLIC",
      "delivery_text": "Thanks again bud!",
      "additional_information": [
        {
          "required": true,
          "key": "3aecffd000e00e2211e94558007ffc37",
          "type": "CHECKBOX",
          "label": "Do you agree to handing your soul over?"
        }
      ],
      "other_settings": {
        "faq": [
          {
            "answer": "Yes, trust me!",
            "question": "Will I really live forever?"
          }
        ],
        "video_url": "https:\/\/www.youtube.com\/watch?v=dQw4w9WgXcQ",
        "redirect_url": "https:\/\/666.com\/transfer-soul?customer_email=[customer_email]&order_id=[order_id]",
        "product_title": "The real elixir of immortality",
        "product_description": "Live forever, online."
      },
      "deleted_at": null,
      "created_at": "2024-01-09T22:56:49.000000Z",
      "updated_at": "2024-01-10T10:00:28.000000Z",
      "store_id": 1,
      "category_id": null,
      "section_id": null,
      "section_order": null,
      "is_discoverable": 1,
      "variants": [
        {
          "id": 1,
          "title": "Default"
        }
      ],
      "url": "https:\/\/example.sell.app\/product\/elixir-of-immortality"
    }
  ],
  "links": {
    // ...
  },
  "meta": {
    // ...
  }
}
POST/v2/products

Create a product

Programmatically create a product using the following endpoint. See the code examples for how to create a new product with the SellApp API.

Unlike other endpoints, we will be using Multipart instead of JSON so we can add a product image.

If you do not wish to add a product image, you may modify the request and use JSON instead.

This will create a draft product. To complete the product, you will want to create a product variant via the product variant endpoint

Required attributes

  • Name
    title
    Type
    string
    Description

    The product title.

  • Name
    description
    Type
    string
    Description

    The product description.

  • Name
    visibility
    Type
    string
    Description

    The product visibility. One of four values:

    • PUBLIC Product can be visited and purchased.
    • ON_HOLD Product can be visited but not be purchased.
    • HIDDEN Product can be only visited via direct link and purchased.
    • PRIVATE Product cannot be visited or purchased.

Optional attributes

  • Name
    additional_information
    Type
    array
    Description

    The additional information input(s) of the product. Array consists of:

    • required Boolean which pecifies whether the additional information is required
    • type One of five values:
      • TEXT
      • NUMBER
      • HIDDEN
      • TEXTAREA
      • CHECKBOX
    • label The name of the additional information input. Examples:
      • TEXT "What is your in-game username?"
      • NUMBER "Enter your mobile number on which you'd like to receive this top-up"
      • HIDDEN n.a. (as this is a hidden input not visible to the end-user)
      • TEXTAREA "Tell us in detail how you'd like your website to be customized"
      • CHECKBOX "Do you agree to my terms of service?"
  • Name
    images
    Type
    object
    Description

    The image(s) displaying the product.

    To add an image, send a Multipart request with the image uploaded in the request. JSON will not work.

  • Name
    other_settings
    Type
    array
    Description

    Customization settings of the product, with the following options:

    • redirect_url URL you want to redirect your customers to after a successful purchase. The redirect URL can utilize the following dynamic values:
      • [order_id] ID of the order
      • [customer_email] email of the customer who placed the order
    • video_url URL of a product video, will be displayed on product page. Supported services: YouTube, Vimeo, Dailymotion, Slideshare, Miro
    • product_title Meta title element of the product, will appear in search engines and social media.
    • product_description Meta description element of the product, will appear in search engines and social media.
    • faq Array of frequently asked questions to be displayed on the product page. Consists of:
      • question FAQ question.
      • answer FAQ answer.

Request

POST
/v2/products
$client = new http\Client;
$request = new http\Client\Request;

$body = new http\Message\Body;
$body->addForm([
  'title' => 'Immortality Elixir',
  'description' => 'Want to live forever? Buy this now and I'll send a digital elixir that converts your soul into an NFT that will roam the internet for eternity!',
  'visibility' => 'PUBLIC',
  'delivery_text' => 'Thanks for purchasing! Here is a 20% off coupon for your next purchase: 20FREE24',
  'additional_information[0][type]' => 'checkbox',
  'additional_information[0][required]' => '1',
  'additional_information[0][label]' => 'I agree to handing over my soul',
  'other_settings[redirect_url]' => 'https://666.com/transfer-soul?customer_email=[customer_email]&order_id=[order_id]',
  'other_settings[video_url]' => 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
  'other_settings[product_title]' => 'The real elixir of immortality',
  'other_settings[product_description]' => 'Live forever, online.',
  'other_settings[faq][0][question]' => 'Will I really live forever?',
  'other_settings[faq][0][answer]' => 'Yes, trust me!'
], [
  [
    'name' => 'images[]',
    'type' => null,
    'file' => 'path\\to\\image.png',
    'data' => null
  ]
]);

$request->setRequestUrl('https://sell.app/api/v2/products');
$request->setRequestMethod('POST');
$request->setBody($body);

$request->setHeaders([
  'Authorization' => 'Bearer {ApiKeyHere}'
]);

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

Response

{
  "data": {
    "id": 2,
    "title": "Immortality Elixir",
    "slug": "immortality-elixir",
    "description": "Want to live forever? Buy this now and I'll send a digital elixir that converts your soul into an NFT that will roam the internet for eternity!",
    "images": [
      {
        "path": "store\/1\/listings\/qXZHzR15vs09zbfn3yui5jO6QK0IbQP4M6QVydUn.png",
        "metadata": {
          "size": 39289,
          "filename": "qXZHzR15vs09zbfn3yui5jO6QK0IbQP4M6QVydUn",
          "extension": "png",
          "mime_type": "image\/png"
        }
      }
    ],
    "order": 2,
    "visibility": "PUBLIC",
    "delivery_text": "Thanks for purchasing! Here is a 20% off coupon for your next purchase: 20FREE24",
    "additional_information": [
      {
        "required": true,
        "key": "5ebae238c0afae7f4a4b96b30ff6f34c",
        "type": "CHECKBOX",
        "label": "I agree to handing over my soul"
      }
    ],
    "other_settings": {
      "faq": [
        {
          "answer": "Yes, trust me!",
          "question": "Will I really live forever?"
        }
      ],
      "video_url": "https:\/\/www.youtube.com\/watch?v=dQw4w9WgXcQ",
      "redirect_url": "https:\/\/666.com\/transfer-soul?customer_email=[customer_email]&order_id=[order_id]",
      "product_title": "The real elixir of immortality",
      "product_description": "Live forever, online."
    },
    "deleted_at": null,
    "created_at": "2024-01-10T12:16:10.000000Z",
    "updated_at": "2024-01-10T12:16:10.000000Z",
    "store_id": 1,
    "category_id": null,
    "section_id": null,
    "section_order": null,
    "is_discoverable": 1,
    "variants": [],
    "url": "https:\/\/example.sell.app\/product\/immortality-elixir"
  }
}
GET/v2/products/:id

Retrieve a product

This endpoint allows you to retrieve a specific product by providing the unique identifier. Refer to the list at the top of this page to see which properties are included with product objects.

Request

GET
/v2/products/:id
$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://sell.app/api/v2/products/1');
$request->setRequestMethod('GET');
$request->setHeaders([
  'accept' => 'application/json',
  'Authorization' => 'Bearer {ApiKeyHere}'
]);

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

Response

{
  "data": [
    {
      "id": 1,
      "title": "Elixir of immortality",
      "slug": "elixir-of-immortality",
      "description": "<p>Want to live forever? Buy this now and I'll send a digital elixir that converts your soul into an NFT that will roam the internet for eternity!<\/p>",
      "images": [
        {
          "path": "store\/1\/listings\/NM6TBKIMzpFJq1MKTV24oMJ1W4UrKCo7NS98nt4K.png",
          "metadata": {
            "size": 39289,
            "filename": "NM6TBKIMzpFJq1MKTV24oMJ1W4UrKCo7NS98nt4K",
            "extension": "png",
            "mime_type": "image\/png"
          }
        },
        {
          "path": "store\/1\/listings\/ov6XMb68tRr80zl7sqfN1or7xfqqH5WbZygDEQ8X.png",
          "metadata": {
            "size": 422373,
            "filename": "ov6XMb68tRr80zl7sqfN1or7xfqqH5WbZygDEQ8X",
            "extension": "png",
            "mime_type": "image\/png"
          }
        }
      ],
      "order": 1,
      "visibility": "PUBLIC",
      "delivery_text": "Thanks again bud!",
      "additional_information": [
        {
          "required": true,
          "key": "3aecffd000e00e2211e94558007ffc37",
          "type": "CHECKBOX",
          "label": "Do you agree to handing your soul over?"
        }
      ],
      "other_settings": {
        "faq": [
          {
            "answer": "Yes, trust me!",
            "question": "Will I really live forever?"
          }
        ],
        "video_url": "https:\/\/www.youtube.com\/watch?v=dQw4w9WgXcQ",
        "redirect_url": "https:\/\/666.com\/transfer-soul?customer_email=[customer_email]&order_id=[order_id]",
        "product_title": "The real elixir of immortality",
        "product_description": "Live forever, online."
      },
      "deleted_at": null,
      "created_at": "2024-01-09T22:56:49.000000Z",
      "updated_at": "2024-01-10T10:00:28.000000Z",
      "store_id": 1,
      "category_id": null,
      "section_id": null,
      "section_order": null,
      "is_discoverable": 1,
      "variants": [
        {
          "id": 1,
          "title": "Default"
        }
      ],
      "url": "https:\/\/example.sell.app\/product\/elixir-of-immortality"
    }
  ],
  "links": {
    // ...
  },
  "meta": {
    // ...
  }
}
PATCH/v2/products/:id

Update a product

Update a product's details with the following endpoint.

Optional attributes

  • Name
    title
    Type
    string
    Description

    The product title.

  • Name
    description
    Type
    string
    Description

    The product description.

  • Name
    visibility
    Type
    string
    Description

    The product visibility. One of four values:

    • PUBLIC Product can be visited and purchased.
    • ON_HOLD Product can be visited but not be purchased.
    • HIDDEN Product can be only visited via direct link and purchased.
    • PRIVATE Product cannot be visited or purchased.
  • Name
    additional_information
    Type
    array
    Description

    The additional information input(s) of the product. Array consists of:

    • required Boolean which pecifies whether the additional information is required
    • type One of five values:
      • TEXT
      • NUMBER
      • HIDDEN
      • TEXTAREA
      • CHECKBOX
    • label The name of the additional information input. Examples:
      • TEXT "What is your in-game username?"
      • NUMBER "Enter your mobile number on which you'd like to receive this top-up"
      • HIDDEN n.a. (as this is a hidden input not visible to the end-user)
      • TEXTAREA "Tell us in detail how you'd like your website to be customized"
      • CHECKBOX "Do you agree to my terms of service?"
  • Name
    images
    Type
    object
    Description

    The image(s) displaying the product.

    To add an image, send a Multipart request with the image uploaded in the request. JSON will not work.

  • Name
    other_settings
    Type
    array
    Description

    Customization settings of the product, with the following options:

    • redirect_url URL you want to redirect your customers to after a successful purchase. The redirect URL can utilize the following dynamic values:
      • [order_id] ID of the order
      • [customer_email] email of the customer who placed the order
    • video_url URL of a product video, will be displayed on product page. Supported services: YouTube, Vimeo, Dailymotion, Slideshare, Miro
    • product_title Meta title element of the product, will appear in search engines and social media.
    • product_description Meta description element of the product, will appear in search engines and social media.
    • faq Array of frequently asked questions to be displayed on the product page. Consists of:
      • question FAQ question.
      • answer FAQ answer.

Request

PATCH
/v2/products/:id
$client = new http\Client;
$request = new http\Client\Request;

$body = new http\Message\Body;
$body->append('{
  "description": "Updated Description"
}');

$request->setRequestUrl('https://sell.app/api/v2/products/2');
$request->setRequestMethod('PATCH');
$request->setBody($body);

$request->setHeaders([
  'content-type' => 'application/json',
  'Accept' => 'text/json',
  'Authorization' => 'Bearer {ApiKeyHere}'
]);

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

Response

{
  "data": {
    "id": 2,
    "title": "Immortality Elixir",
    "slug": "immortality-elixir",
    "description": "Updated Description",
    "images": [
      {
        "path": "store\/1\/listings\/qXZHzR15vs09zbfn3yui5jO6QK0IbQP4M6QVydUn.png",
        "metadata": {
          "size": 39289,
          "filename": "qXZHzR15vs09zbfn3yui5jO6QK0IbQP4M6QVydUn",
          "extension": "png",
          "mime_type": "image\/png"
        }
      }
    ],
    "order": 2,
    "visibility": "PUBLIC",
    "delivery_text": "Thanks for purchasing! Here is a 20% off coupon for your next purchase: 20FREE24",
    "additional_information": [
      {
        "required": true,
        "key": "5ebae238c0afae7f4a4b96b30ff6f34c",
        "type": "CHECKBOX",
        "label": "I agree to handing over my soul"
      }
    ],
    "other_settings": {
      "faq": [
        {
          "answer": "Yes, trust me!",
          "question": "Will I really live forever?"
        }
      ],
      "video_url": "https:\/\/www.youtube.com\/watch?v=dQw4w9WgXcQ",
      "redirect_url": "https:\/\/666.com\/transfer-soul?customer_email=[customer_email]&order_id=[order_id]",
      "product_title": "The real elixir of immortality",
      "product_description": "Live forever, online."
    },
    "deleted_at": null,
    "created_at": "2024-01-10T12:16:10.000000Z",
    "updated_at": "2024-01-10T12:16:10.000000Z",
    "store_id": 1,
    "category_id": null,
    "section_id": null,
    "section_order": null,
    "is_discoverable": 1,
    "variants": [],
    "url": "https:\/\/example.sell.app\/product\/immortality-elixir"
  }
}
DELETE/v2/products/:id

Delete a product

This endpoint allows you to delete a product.

This will permanently delete the product and its associated data.

Request

DELETE
/v2/products/:id
$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://sell.app/api/v2/products/2');
$request->setRequestMethod('DELETE');
$request->setHeaders([
  'accept' => 'application/json',
  'Authorization' => 'Bearer {ApiKeyHere}'
]);

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();