Seller API

Integrate with Fieldfolio.

Table of contents

Usage
Authentication
Catalogs
Customers
Orders
Products
Publish a catalog

Usage

Your use of the Fieldfolio API service is subject to the Fieldfolio Terms of Service.

The API accepts only JSON requests. Please make sure you're setting Accept: application/json in your request header. Each request returns a JSON-encoded body.

The result of each action is communicated via standard HTTP response codes.

Successful requests

When request is successful (2xx), a nested response object is returned.

Example request

curl -v \
     -H "Accept: application/json" \
     -X GET https://app.fieldfolio.com/api/v1/catalogs?user_credentials=ACCESS_TOKEN

Response

[
  {
    "id": 25,
    "name": "Fieldfolio Demo Catalog",
    "created_at": "2013-02-28 12:37",
    "updated_at": "2015-09-30 22:55",
    "last_published_at": "2015-09-30 06:57",
    "last_changed_at": "2013-02-28 12:37",
    "photo_url": "https://app.fieldfolio.dev/system/catalogs/photos/000/000/025/original/blue-frog.png?1440041698",
    "account": {
      "id": 25,
      "name": "Corrupt Co",
      "tax_rate_1_label": "Tax 1",
      "tax_rate_1": 0.0,
      "tax_rate_2_label": "Tax 2",
      "tax_rate_2": null,
      "created_at": "2013-02-28 12:37",
      "updated_at": "2015-09-30 07:10",
      "timezone": "Melbourne",
      "currency_code": "usd",
      "currency_symbol": "$",
      "account_address": {
        "id": 81926,
        "name": "",
        "phone": "",
        "fax": "",
        "email": "",
        "street_1": "21 Jump Street",
        "street_2": "",
        "city": "",
        "state": "",
        "country": "Australia",
        "postcode": "",
        "contact": "",
        "phone_2": "",
        "created_at": "2015-07-12 06:13",
        "updated_at": "2015-07-12 06:13"
      },
      "logo_url": "https://app.fieldfolio.dev/system/accounts/logos/000/000/025/thumb/frog.png?1441861060"
    }
  }
]

Failed requests

Failed requests will return a HTTP status code (4xx, 5xx). No other data will be returned.

Sending JSON data

Some API requests will require you to send JSON data. (i.e. logging in, creating a product, etc)

For these requests, JSON data must be sent using POST, and must be sent raw, NOT as a string.

Please make sure you understand how to send JSON data raw using your HTTP library. JSON data encoded as a string will be rejected by our API.

Authentication

To use the API, you need to authenticate yourself. This can be done via HTTP POST. After successful authentication an access token is returned.

If authentication fails, HTTP status code 403 is returned.

HTTP POST Auth with e-mail and password

Example request

curl -v \
     -d '{"user_session":{"email":"enquiries@possigroup.com","password":"your_password"}}' \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -X POST https://app.fieldfolio.com/api/v1/user_sessions

Response

  {
    "user_credential":"ACCESS_TOKEN",
    "email":"enquiries@possigroup.com",
    "full_name":"Deborah Chan"
  }

You can then append the access token to any subsequent API calls to authenticate them.

Example request

curl -v \
     -H "Accept: application/json" \
     -X GET https://app.fieldfolio.com/api/v1/catalogs?user_credentials=ACCESS_TOKEN

Catalogs

Get all catalogs visible to user

Example request

curl -v \
     -H "Accept: application/json" \
     -X GET https://app.fieldfolio.com/api/v1/catalogs?user_credentials=ACCESS_TOKEN

Response

[
  {
    "id": 25,
    "name": "Fieldfolio Demo Catalog",
    "created_at": "2013-02-28 12:37",
    "updated_at": "2015-09-30 22:55",
    "last_published_at": "2015-09-30 06:57",
    "last_changed_at": "2013-02-28 12:37",
    "photo_url": "https://app.fieldfolio.dev/system/catalogs/photos/000/000/025/original/blue-frog.png?1440041698",
    "account": {
      "id": 25,
      "name": "Corrupt Co",
      "tax_rate_1_label": "Tax 1",
      "tax_rate_1": 0.0,
      "tax_rate_2_label": "Tax 2",
      "tax_rate_2": null,
      "created_at": "2013-02-28 12:37",
      "updated_at": "2015-09-30 07:10",
      "timezone": "Melbourne",
      "currency_code": "usd",
      "currency_symbol": "$",
      "account_address": {
        "id": 81926,
        "name": "",
        "phone": "",
        "fax": "",
        "email": "",
        "street_1": "21 Jump Street",
        "street_2": "",
        "city": "",
        "state": "",
        "country": "Australia",
        "postcode": "",
        "contact": "",
        "phone_2": "",
        "created_at": "2015-07-12 06:13",
        "updated_at": "2015-07-12 06:13"
      },
      "logo_url": "https://app.fieldfolio.dev/system/accounts/logos/000/000/025/thumb/frog.png?1441861060"
    }
  }
]

Get specific catalog

Example request

curl -v \
     -H "Accept: application/json" \
     -X GET https://app.fieldfolio.com/api/v1/catalogs/CATALOG_ID?user_credentials=ACCESS_TOKEN

Response

{
  "id": 25,
  "name": "Fieldfolio Demo Catalog",
  "created_at": "2013-02-28 12:37",
  "updated_at": "2015-09-30 22:55",
  "last_published_at": "2015-09-30 06:57",
  "last_changed_at": "2013-02-28 12:37",
  "categories": [
    {
      "id": 23,
      "name": "Plush",
      "taggings_count": 48
    },
    {
      "id": 24,
      "name": "Toys",
      "taggings_count": 68
    },
    {
      "id": 26,
      "name": "Beatrix Potter",
      "taggings_count": 103
    },
    {
      "id": 27,
      "name": "Table Top",
      "taggings_count": 141
    },
    {
      "id": 28,
      "name": "Print Range",
      "taggings_count": 121
    },
    {
      "id": 29,
      "name": "Textiles",
      "taggings_count": 66
    },
    {
      "id": 30,
      "name": "Gifts",
      "taggings_count": 56
    },
    {
      "id": 31,
      "name": "Dinnnerware",
      "taggings_count": 128
    },
    {
      "id": 32,
      "name": "Garden",
      "taggings_count": 172
    },
    {
      "id": 33,
      "name": "Jewellery",
      "taggings_count": 84
    },
    {
      "id": 34,
      "name": "Mensware",
      "taggings_count": 72
    },
    {
      "id": 35,
      "name": "Clothing",
      "taggings_count": 132
    },
    {
      "id": 36,
      "name": "Shirts",
      "taggings_count": 32
    }
  ],
  "photo_url": "https://app.fieldfolio.dev/system/catalogs/photos/000/000/025/original/blue-frog.png?1440041698"
}

Customers

Get all customers visible to user

Example request

curl -v \
     -H "Accept: application/json" \
     -X GET https://app.fieldfolio.com/api/v1/customers?user_credentials=ACCESS_TOKEN

You can also pass a created_since parameter, to only return those customers created since a certain date. (note: this parameter uses ISO 8601 format)

curl -v \
     -H "Accept: application/json" \
     -X GET https://app.fieldfolio.com/api/v1/customers?created_since=2020-08-26T19%3A25%3A39%2B10%3A00&user_credentials=ACCESS_TOKEN

Response

[
  {
    "id": 9439,
    "reference": "",
    "name": "Example Customer",
    "contact": "Joe Blow",
    "phone": "+1334234343",
    "fax": null,
    "email": "example@example.com",
    "created_at": "2015-01-27 06:43",
    "updated_at": "2015-04-26 05:13",
    "billing_address": {
      "id": 81885,
      "name": "Joe Blow's Company",
      "phone": "",
      "fax": "",
      "email": "example@example.com",
      "street_1": "21 Jump Street",
      "street_2": "",
      "city": "Melbourne",
      "state": "VIC",
      "country": "Australia",
      "postcode": "3000",
      "contact": "Joe Blow",
      "phone_2": "",
      "created_at": "2015-01-27 06:43",
      "updated_at": "2015-04-27 23:54"
    },
    "delivery_addresses": [
      {
        "id": 81886,
        "name": "Joe Blow's Company",
        "phone": "",
        "fax": "",
        "email": "example@example.com",
        "street_1": "21 Jump Street",
        "street_2": "",
        "city": "Melbourne",
        "state": "VIC",
        "country": "Australia",
        "postcode": "3800",
        "contact": "Joe Blow",
        "phone_2": "",
        "created_at": "2015-01-27 06:43",
        "updated_at": "2015-04-27 23:54"
      }
    ]
  }
]

Get specific customer

Example request

curl -v \
     -H "Accept: application/json" \
     -X GET https://app.fieldfolio.com/api/v1/customers/596028?user_credentials=ACCESS_TOKEN

Response

{
    "id": 9439,
    "reference": "",
    "name": "Example Customer",
    "contact": "Joe Blow",
    "phone": "+1334234343",
    "fax": null,
    "email": "example@example.com",
    "created_at": "2015-01-27 06:43",
    "updated_at": "2015-04-26 05:13",
    "billing_address": {
      "id": 81885,
      "name": "Joe Blow's Company",
      "phone": "",
      "fax": "",
      "email": "example@example.com",
      "street_1": "21 Jump Street",
      "street_2": "",
      "city": "Melbourne",
      "state": "VIC",
      "country": "Australia",
      "postcode": "3000",
      "contact": "Joe Blow",
      "phone_2": "",
      "created_at": "2015-01-27 06:43",
      "updated_at": "2015-04-27 23:54"
    },
    "delivery_addresses": [
      {
        "id": 81886,
        "name": "Joe Blow's Company",
        "phone": "",
        "fax": "",
        "email": "example@example.com",
        "street_1": "21 Jump Street",
        "street_2": "",
        "city": "Melbourne",
        "state": "VIC",
        "country": "Australia",
        "postcode": "3800",
        "contact": "Joe Blow",
        "phone_2": "",
        "created_at": "2015-01-27 06:43",
        "updated_at": "2015-04-27 23:54"
      }
    ]
  }

Create a Customer

Example request

curl -v \
     -d '{
          "customer": {
            "name": "Joe Blows Company", "reference": "",
            "delivery_addresses_attributes": [
              {"name": "Joe Blow", "street_1": "100 Heidi St", "street_2": "", "city": "Melbourne", "state": "VIC", "postcode": "3000", "country": "Australia", "phone": "0351000000", "phone_2": "0412341234", "fax": "", "contact": "Joe Blow"}
            ],
            "billing_address_attributes": {
              "name": "Joe Blow", "street_1": "100 Heidi St", "street_2": "", "city": "Melbourne", "state": "VIC", "postcode": "3000", "country": "Australia", "phone": "0351000000", "phone_2": "0412341234", "fax": "", "contact": "Joe Blow"
            }
          }
        }' \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -X POST https://app.fieldfolio.com/api/v1/customers?user_credentials=ACCESS_TOKEN

Response

  {
      "id": 9446,
      "reference": "",
      "name": "Joe Blows Company",
      "contact": null,
      "phone": null,
      "fax": null,
      "email": null,
      "created_at": "2015-11-04 10:59",
      "updated_at": "2015-11-04 10:59",
      "billing_address": {
          "id": 81946,
          "name": "Joe Blow",
          "phone": "0351000000",
          "fax": "",
          "email": null,
          "street_1": "100 Heidi St",
          "street_2": "",
          "city": "Melbourne",
          "state": "VIC",
          "country": "Australia",
          "postcode": "3000",
          "contact": "Joe Blow",
          "phone_2": "0412341234",
          "created_at": "2015-11-04 10:59",
          "updated_at": "2015-11-04 10:59"
      },
      "delivery_addresses": [{
          "id": 81947,
          "name": "Joe Blow",
          "phone": "0351000000",
          "fax": "",
          "email": null,
          "street_1": "100 Heidi St",
          "street_2": "",
          "city": "Melbourne",
          "state": "VIC",
          "country": "Australia",
          "postcode": "3000",
          "contact": "Joe Blow",
          "phone_2": "0412341234",
          "created_at": "2015-11-04 10:59",
          "updated_at": "2015-11-04 10:59"
      }]
  }

Update a Customer

To update an existing customer or address, you must pass through the relevant customer and address IDs.

Example request

curl -v \
     -d '{
          "id": 9446,
          "customer": {
            "name": "Joe Blows Company", "reference": "",
            "delivery_addresses_attributes": [
              {"id": 81946, "name": "Joe Blow", "street_1": "100 Heidi St", "street_2": "", "city": "Melbourne", "state": "VIC", "postcode": "3000", "country": "Australia", "phone": "0351000000", "phone_2": "0412341234", "fax": "", "contact": "Joe Blow"}
            ],
            "billing_address_attributes": {
              "id": 81947, "name": "Joe Blow", "street_1": "100 Heidi St", "street_2": "", "city": "Melbourne", "state": "VIC", "postcode": "3000", "country": "Australia", "phone": "0351000000", "phone_2": "0412341234", "fax": "", "contact": "Joe Blow"
            }
          }
        }' \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -X PATCH https://app.fieldfolio.com/api/v1/customers?user_credentials=ACCESS_TOKEN

Response

  {
      "id": 9446,
      "reference": "",
      "name": "Joe Blows Company",
      "contact": null,
      "phone": null,
      "fax": null,
      "email": null,
      "created_at": "2015-11-04 10:59",
      "updated_at": "2015-11-04 10:59",
      "billing_address": {
          "id": 81946,
          "name": "Joe Blow",
          "phone": "0351000000",
          "fax": "",
          "email": null,
          "street_1": "100 Heidi St",
          "street_2": "",
          "city": "Melbourne",
          "state": "VIC",
          "country": "Australia",
          "postcode": "3000",
          "contact": "Joe Blow",
          "phone_2": "0412341234",
          "created_at": "2015-11-04 10:59",
          "updated_at": "2015-11-04 10:59"
      },
      "delivery_addresses": [{
          "id": 81947,
          "name": "Joe Blow",
          "phone": "0351000000",
          "fax": "",
          "email": null,
          "street_1": "100 Heidi St",
          "street_2": "",
          "city": "Melbourne",
          "state": "VIC",
          "country": "Australia",
          "postcode": "3000",
          "contact": "Joe Blow",
          "phone_2": "0412341234",
          "created_at": "2015-11-04 10:59",
          "updated_at": "2015-11-04 10:59"
      }]
  }

Destroy an existing customer

Example request

curl -v \
     -H "Accept: application/json" \
     -X DELETE https://app.fieldfolio.com/api/v1/customers/9446?user_credentials=ACCESS_TOKEN

Where 9446 is the ID of the customer you want to delete.

Response

  status: 200 OK

Orders

Get all orders visible to user

Example request

curl -v \
     -H "Accept: application/json" \
     -X GET https://app.fieldfolio.com/api/v1/orders?user_credentials=ACCESS_TOKEN

You can also pass a created_since parameter, to only return those orders created since a certain date. (note: this parameter uses ISO 8601 format)

curl -v \
     -H "Accept: application/json" \
     -X GET https://app.fieldfolio.com/api/v1/orders?created_since=2020-08-26T19%3A25%3A39%2B10%3A00&user_credentials=ACCESS_TOKEN

The returned data is paginated, by default 20 records per page. You can fetch additional pages by passing a page parameter. Or change the records per page with per_page.

curl -v \
     -H "Accept: application/json" \
     -X GET https://app.fieldfolio.com/api/v1/orders?page=2&user_credentials=ACCESS_TOKEN

Response

[
  {
    "id": 31011,
    "account_id": 25,
    "catalog_id": 25,
    "catalog_name": "Fieldfolio Demo Catalog",
    "customer_id": 9422,
    "customer_name": "Joe Blow's Company",
    "customer_reference": "",
    "user_id": 53,
    "note": null,
    "tos": "",
    "reference": null,
    "hold": null,
    "shipping_date": null,
    "cancel_date": null,
    "shipping_partial": null,
    "shipping_method": null,
    "category": null,
    "payment": null,
    "total_amount": "48.0",
    "tax_amount": "0.0",
    "created_at": "2015-10-09 00:18",
    "updated_at": "2015-10-09 00:18",
    "grand_total": "48.0",
    "tax_1_label": "Tax 1",
    "tax_1_amount": "0.0",
    "tax_2_label": "Tax 2",
    "tax_2_amount": "0.0",
    "tax_1_rate": 0.0,
    "tax_2_rate": null,
    "currency_code": "usd",
    "currency_symbol": "$",
    "source": 20,
    "user_name": "Joe Blow"
  }
]

Get specific order

Example request

curl -v \
     -H "Accept: application/json" \
     -X GET https://app.fieldfolio.com/api/v1/orders/0?user_credentials=ACCESS_TOKEN

Response

{
  "id": 31011,
  "account_id": 25,
  "catalog_id": 25,
  "catalog_name": "Staging Demo Catalog",
  "customer_id": 9422,
  "customer_name": "Joe Blow's Company",
  "customer_reference": "",
  "user_id": 53,
  "note": null,
  "tos": "",
  "reference": null,
  "hold": null,
  "shipping_date": null,
  "cancel_date": null,
  "shipping_partial": null,
  "shipping_method": null,
  "category": null,
  "payment": null,
  "total_amount": "48.0",
  "tax_amount": "0.0",
  "created_at": "2015-10-09 00:18",
  "updated_at": "2015-10-09 00:18",
  "grand_total": "48.0",
  "tax_1_label": "Tax 1",
  "tax_1_amount": "0.0",
  "tax_2_label": "Tax 2",
  "tax_2_amount": "0.0",
  "tax_1_rate": 0.0,
  "tax_2_rate": null,
  "currency_code": "usd",
  "currency_symbol": "$",
  "source": 20,
  "account_address": {
    "id": 81941,
    "name": "",
    "phone": "",
    "fax": "",
    "email": "",
    "street_1": "21 Jump Street",
    "street_2": "",
    "city": "",
    "state": "",
    "country": "Australia",
    "postcode": "",
    "contact": "",
    "phone_2": "",
    "created_at": "2015-10-09 00:18",
    "updated_at": "2015-10-09 00:18"
  },
  "delivery_address": {
    "id": 81943,
    "name": "Joe Blow's Company",
    "phone": "",
    "fax": "",
    "email": "example@example.com",
    "street_1": "1234",
    "street_2": "",
    "city": "",
    "state": "",
    "country": null,
    "postcode": "",
    "contact": "",
    "phone_2": "",
    "created_at": "2015-10-09 00:18",
    "updated_at": "2015-10-09 00:18"
  },
  "billing_address": {
    "id": 81942,
    "name": "Joe Blow's Company",
    "phone": "",
    "fax": "",
    "email": "example@example.com",
    "street_1": "1234",
    "street_2": "",
    "city": "",
    "state": "",
    "country": null,
    "postcode": "",
    "contact": "",
    "phone_2": "",
    "created_at": "2015-10-09 00:18",
    "updated_at": "2015-10-09 00:18"
  },
  "order_lines": [
    {
      "id": 110382,
      "product_id": 45066,
      "name": "Black White Printed 6 Seater Table Cloth",
      "extended_description": "Printed cotton Table Cloth 6 seater 150 x 220cm color fast machine washable.",
      "badge": null,
      "hero": false,
      "created_at": "2015-10-09 00:18",
      "updated_at": "2015-10-09 00:18",
      "order_line_items": [
        {
          "id": 115395,
          "variety_id": 51779,
          "quantity": 2,
          "name": null,
          "price": "24.0",
          "rrp": "0.0",
          "unit": "Each",
          "sku": "STC1205-BlackWhite",
          "barcode": null,
          "stock_on_hand": 234,
          "stock_due_date": null,
          "minimum_order_quantity": 2,
          "created_at": "2015-10-09 00:18",
          "updated_at": "2015-10-09 00:18",
          "total_amount": "48.0",
          "tax_amount": "0.0",
          "grand_total": "48.0",
          "tax_1_amount": "0.0",
          "tax_2_amount": "0.0"
        }
      ]
    }
  ],
  "user_name": "Joe Blow"
}

Products

A note on `draft` vs `published` Products

For every product there are two records stored in the system. The draft record and a published record. This is so we can keep track of both your draft changes, and the live published version (which is visible in the iPad app and Fieldfolio Marketplace). When you update a product, those changes are always made to the draft version, and when the catalog is published the changes are copied them over the published version. You can only update or delete the draft products using this API.

When fetching products, this API endpoint can return either the draft product records, or the published product records, or both. Append a ?version= param to control this. I.e. ?version=published, ?version=draft, ?version=any The default is to return the published records.

Get all products visible to user

Example request

curl -v \
     -H "Accept: application/json" \
     -X GET https://app.fieldfolio.com/api/v1/catalogs/CATALOG_ID/products?user_credentials=ACCESS_TOKEN

Response

[
  {
    "id": 45053,
    "catalog_id": 25,
    "position": 1,
    "name": "Soft Toy Ernie",
    "description": null,
    "extended_description": "Sesame Street's Ernie 24 cm plush wears his blue pants and striped sweater. Ernie likes using his imagination, taking baths with Rubber Duckie, and joking around with his best buddy Bert. Ernie will make a fun playtime companion for your child. 24  cm Age Range BIRTH +",
    "hero": true,
    "hidden": false,
    "taxable_1": true,
    "taxable_2": false,
    "created_at": "2013-03-22 09:55",
    "updated_at": "2015-09-30 06:15",
    "published_at": "2015-09-30 06:15",
    "varieties": [
      {
        "id": 51760,
        "name": "",
        "price": "12.0",
        "rrp": null,
        "unit": "Each",
        "sku": "U75365",
        "barcode": "",
        "stock_on_hand": null,
        "stock_due_date": null,
        "minimum_order_quantity": 1,
        "default_order_quantity": null,
        "summary": null,
        "created_at": "2013-03-22 09:55",
        "updated_at": "2015-09-30 02:48"
      }
    ],
    "pictures": [
      {
        "created_at": "2015-09-30 02:48",
        "updated_at": "2015-09-30 02:48",
        "original_photo_url": "https://app.fieldfolio.dev/system/pictures/photos/000/000/002/original/SGC80_1.jpg?1443581332",
        "grid_photo_url": "https://app.fieldfolio.dev/system/pictures/photos/000/000/002/hero/SGC80_1.jpg?1443581332",
        "hero_photo_url": "https://app.fieldfolio.dev/system/pictures/photos/000/000/002/hero/SGC80_1.jpg?1443581332",
        "list_photo_url": "https://app.fieldfolio.dev/system/pictures/photos/000/000/002/list/SGC80_1.jpg?1443581332"
      }
    ],
    "badge_label": "new",
    "categories": [
      394
    ]
  }
]

Get specific product

Example request

curl -v \
     -H "Accept: application/json" \
     -X GET https://app.fieldfolio.com/api/v1/catalogs/CATALOG_ID/products/812091?user_credentials=ACCESS_TOKEN

Response

{
  "id": 45053,
  "catalog_id": 25,
  "position": 1,
  "name": "Soft Toy Ernie",
  "description": null,
  "extended_description": "Sesame Street's Ernie 24 cm plush wears his blue pants and striped sweater. Ernie likes using his imagination, taking baths with Rubber Duckie, and joking around with his best buddy Bert. Ernie will make a fun playtime companion for your child. 24  cm Age Range BIRTH +",
  "hero": true,
  "hidden": false,
  "taxable_1": true,
  "taxable_2": false,
  "created_at": "2013-03-22 09:55",
  "updated_at": "2015-09-30 06:15",
  "published_at": "2015-09-30 06:15",
  "varieties": [
    {
      "id": 51760,
      "name": "",
      "price": "12.0",
      "rrp": null,
      "unit": "Each",
      "sku": "U75365",
      "barcode": "",
      "stock_on_hand": null,
      "stock_due_date": null,
      "minimum_order_quantity": 1,
      "default_order_quantity": null,
      "summary": null,
      "created_at": "2013-03-22 09:55",
      "updated_at": "2015-09-30 02:48"
    }
  ],
  "pictures": [
    {
      "created_at": "2015-09-30 02:48",
      "updated_at": "2015-09-30 02:48",
      "original_photo_url": "https://app.fieldfolio.dev/system/pictures/photos/000/000/002/original/SGC80_1.jpg?1443581332",
      "grid_photo_url": "https://app.fieldfolio.dev/system/pictures/photos/000/000/002/hero/SGC80_1.jpg?1443581332",
      "hero_photo_url": "https://app.fieldfolio.dev/system/pictures/photos/000/000/002/hero/SGC80_1.jpg?1443581332",
      "list_photo_url": "https://app.fieldfolio.dev/system/pictures/photos/000/000/002/list/SGC80_1.jpg?1443581332"
    }
  ],
  "badge_label": "new",
  "categories": [
    394
  ]
}

Create a Product

Note that valid values for the following attributes are:

hero: 0 (false), 1 (true)
hidden: 0 (false), 1 (true)
taxable_1: 0 (false), 1 (true)
badge:
- 1 (new)
- 2 (best seller)
- 3 (special)
- 4 (upcoming)
- 5 (sold out)
- 6 (discontinued)

Example request

curl -v \
     -d '{
          "product": {
            "position_adjustment": null, "name": "Test Product", "category_list": "Test Category, Test Category2",
            "badge": 1, "extended_description": "Test extended description", "hero": 0, "hidden": 0, "taxable_1": 1,
            "varieties_attributes": [{
              "sku": "ABCD1234", "barcode": "", "name": "Test Product", "price": "54.3", "unit": "Each",
              "rrp": "100", "minimum_order_quantity": 1, "stock_on_hand": 2,
              "stock_due_date_string": "23/12/2012"
            }]
          }
        }' \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -X POST https://app.fieldfolio.com/api/v1/catalogs/CATALOG_ID/products?user_credentials=ACCESS_TOKEN

Response

  {
      "id": PRODUCT_ID,
      "catalog_id": 25,
      "position": 41,
      "name": "Test Product",
      "description": null,
      "extended_description": "Test extended description",
      "hero": false,
      "hidden": false,
      "taxable_1": true,
      "taxable_2": null,
      "created_at": "2015-11-04 14:41",
      "updated_at": "2015-11-04 14:41",
      "published_at": null,
      "varieties": [{
          "id": 58316,
          "name": "Test Product",
          "price": "54.3",
          "rrp": "100.0",
          "unit": "Each",
          "sku": "ABCD1234",
          "barcode": "",
          "stock_on_hand": 2,
          "stock_due_date": "2012-12-23",
          "minimum_order_quantity": 1,
          "default_order_quantity": null,
          "summary": null,
          "created_at": "2015-11-04 14:41",
          "updated_at": "2015-11-04 14:41"
      }],
      "pictures_with_default": [{
          "created_at": null,
          "updated_at": null,
          "original_photo_url": "https://app.fieldfolio.dev/assets/default_product_original.jpg",
          "grid_photo_url": "https://app.fieldfolio.dev/assets/default_product_hero.jpg",
          "hero_photo_url": "https://app.fieldfolio.dev/assets/default_product_hero.jpg",
          "list_photo_url": "https://app.fieldfolio.dev/assets/default_product_list.jpg"
      }],
      "badge_label": "new",
      "currency_symbol": "$",
      "categories": [396, 397]
  }

Update a Product

To update an existing draft product or variety [#], you must pass through the relevant product and variety IDs.

Example request

curl -v \
     -d '{
          "id": PRODUCT_ID,
          "product": {
            "position_adjustment": null, "name": "Test Product", "category_list": "Test Category, Test Category2",
            "badge": 1, "extended_description": "Test extended description", "hero": 0, "hidden": 0, "taxable_1": 1,
            "varieties_attributes": [{
              "id": 58316,
              "sku": "ABCD1234", "barcode": "", "name": "Test Product", "price": "54.3", "unit": "Each",
              "rrp": "100", "minimum_order_quantity": 1, "stock_on_hand": 2,
              "stock_due_date_string": "23/12/2012"
            }]
          }
        }' \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -X PATCH https://app.fieldfolio.com/api/v1/catalogs/CATALOG_ID/products/PRODUCT_ID?user_credentials=ACCESS_TOKEN

Response

  {
      "id": PRODUCT_ID,
      "catalog_id": 25,
      "position": 41,
      "name": "Test Product",
      "description": null,
      "extended_description": "Test extended description",
      "hero": false,
      "hidden": false,
      "taxable_1": true,
      "taxable_2": null,
      "created_at": "2015-11-04 14:41",
      "updated_at": "2015-11-04 14:41",
      "published_at": null,
      "varieties": [{
          "id": 58316,
          "name": "Test Product",
          "price": "54.3",
          "rrp": "100.0",
          "unit": "Each",
          "sku": "ABCD1234",
          "barcode": "",
          "stock_on_hand": 2,
          "stock_due_date": "2012-12-23",
          "minimum_order_quantity": 1,
          "default_order_quantity": null,
          "summary": null,
          "created_at": "2015-11-04 14:41",
          "updated_at": "2015-11-04 14:41"
      }],
      "pictures_with_default": [{
          "created_at": null,
          "updated_at": null,
          "original_photo_url": "https://app.fieldfolio.dev/assets/default_product_original.jpg",
          "grid_photo_url": "https://app.fieldfolio.dev/assets/default_product_hero.jpg",
          "hero_photo_url": "https://app.fieldfolio.dev/assets/default_product_hero.jpg",
          "list_photo_url": "https://app.fieldfolio.dev/assets/default_product_list.jpg"
      }],
      "badge_label": "new",
      "currency_symbol": "$",
      "categories": [396, 397]
  }

Add a variety to existing product

To add a variety to an existing draft product [#], you just add new variety to the varieties_attributes collection. As it is a new variety, it will not yet have an ID.

Example request

curl -v \
     -d '{
          "id": PRODUCT_ID,
          "product": {
            "position_adjustment": null, "name": "Test Product", "category_list": "Test Category, Test Category2",
            "badge": 1, "extended_description": "Test extended description", "hero": 0, "hidden": 0, "taxable_1": 1,
            "varieties_attributes": [{
              "id": 58316,
              "sku": "ABCD1234", "barcode": "", "name": "Test Product", "price": "54.3", "unit": "Each",
              "rrp": "100", "minimum_order_quantity": 1, "stock_on_hand": 2,
              "stock_due_date_string": "23/12/2012"
            }, {
              "sku": "ABCD2345", "barcode": "", "name": "New Variety", "price": "23.3", "unit": "Each",
              "rrp": "70", "minimum_order_quantity": "", "stock_on_hand": "",
              "stock_due_date_string": ""
            }]
          }
        }' \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -X PATCH https://app.fieldfolio.com/api/v1/catalogs/CATALOG_ID/products/PRODUCT_ID?user_credentials=ACCESS_TOKEN

Response

  {
      "id": PRODUCT_ID,
      "catalog_id": 25,
      "position": 41,
      "name": "Test Product",
      "description": null,
      "extended_description": "Test extended description",
      "hero": false,
      "hidden": false,
      "taxable_1": true,
      "taxable_2": null,
      "created_at": "2015-11-04 14:41",
      "updated_at": "2015-11-04 14:41",
      "published_at": null,
      "varieties": [{
          "id": 58316,
          "name": "Test Product",
          "price": "54.3",
          "rrp": "100.0",
          "unit": "Each",
          "sku": "ABCD1234",
          "barcode": "",
          "stock_on_hand": 2,
          "stock_due_date": "2012-12-23",
          "minimum_order_quantity": 1,
          "default_order_quantity": null,
          "summary": null,
          "created_at": "2015-11-04 14:41",
          "updated_at": "2015-11-04 14:41"
      }, {
          "id": 58317,
          "name": "New Variety",
          "price": "23.3",
          "rrp": "70.0",
          "unit": "Each",
          "sku": "ABCD2345",
          "barcode": "",
          "stock_on_hand": "",
          "stock_due_date": "",
          "minimum_order_quantity": null,
          "default_order_quantity": null,
          "summary": null,
          "created_at": "2015-11-04 14:41",
          "updated_at": "2015-11-04 14:41"
      }],
      "pictures_with_default": [{
          "created_at": null,
          "updated_at": null,
          "original_photo_url": "https://app.fieldfolio.dev/assets/default_product_original.jpg",
          "grid_photo_url": "https://app.fieldfolio.dev/assets/default_product_hero.jpg",
          "hero_photo_url": "https://app.fieldfolio.dev/assets/default_product_hero.jpg",
          "list_photo_url": "https://app.fieldfolio.dev/assets/default_product_list.jpg"
      }],
      "badge_label": "new",
      "currency_symbol": "$",
      "categories": [396, 397]
  }

Remove a variety from an existing product

To remove a variety to an existing draft product [#], you must add include the _destroy attribute in the varieties_attributes collection for the relevant variety. It is not nessesary to provide any other attributes for that variety.

Example request

curl -v \
     -d '{
          "id": PRODUCT_ID,
          "product": {
            "position_adjustment": null, "name": "Test Product", "category_list": "Test Category, Test Category2",
            "badge": 1, "extended_description": "Test extended description", "hero": 0, "hidden": 0, "taxable_1": 1,
            "varieties_attributes": [{
              "id": 58316,
              "sku": "ABCD1234", "barcode": "", "name": "Test Product", "price": "54.3", "unit": "Each",
              "rrp": "100", "minimum_order_quantity": 1, "stock_on_hand": 2,
              "stock_due_date_string": "23/12/2012"
            }, {
              "id": 58317,
              "_destroy": 1
            }]
          }
        }' \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -X PATCH https://app.fieldfolio.com/api/v1/catalogs/CATALOG_ID/products/PRODUCT_ID?user_credentials=ACCESS_TOKEN

Response

  {
      "id": PRODUCT_ID,
      "catalog_id": 25,
      "position": 41,
      "name": "Test Product",
      "description": null,
      "extended_description": "Test extended description",
      "hero": false,
      "hidden": false,
      "taxable_1": true,
      "taxable_2": null,
      "created_at": "2015-11-04 14:41",
      "updated_at": "2015-11-04 14:41",
      "published_at": null,
      "varieties": [{
          "id": 58316,
          "name": "Test Product",
          "price": "54.3",
          "rrp": "100.0",
          "unit": "Each",
          "sku": "ABCD1234",
          "barcode": "",
          "stock_on_hand": 2,
          "stock_due_date": "2012-12-23",
          "minimum_order_quantity": 1,
          "default_order_quantity": null,
          "summary": null,
          "created_at": "2015-11-04 14:41",
          "updated_at": "2015-11-04 14:41"
      }],
      "pictures_with_default": [{
          "created_at": null,
          "updated_at": null,
          "original_photo_url": "https://app.fieldfolio.dev/assets/default_product_original.jpg",
          "grid_photo_url": "https://app.fieldfolio.dev/assets/default_product_hero.jpg",
          "hero_photo_url": "https://app.fieldfolio.dev/assets/default_product_hero.jpg",
          "list_photo_url": "https://app.fieldfolio.dev/assets/default_product_list.jpg"
      }],
      "badge_label": "new",
      "currency_symbol": "$",
      "categories": [396, 397]
  }

Destroy an existing product

Example request

curl -v \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -X DELETE https://app.fieldfolio.com/api/v1/catalogs/CATALOG_ID/products/PRODUCT_ID?user_credentials=ACCESS_TOKEN

Where PRODUCT_ID is the ID of the draft product [#] you want to delete.

NOTE: After you delete a product, you must publish the catalog before the change will be visible to users.

Response

Publish a catalog

The publish will happen in a background process, so you will need to wait a few minutes for it to take effect.

Example request

curl -v \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -X POST https://app.fieldfolio.com/api/v1/catalogs/CATALOG_ID/products/publish?user_credentials=ACCESS_TOKEN

Response

  status: 200 OK

Fieldfolio Help

Seller API

Usage

Successful requests

Failed requests

Sending JSON data

Authentication

Catalogs

Get all catalogs visible to user

Get specific catalog

Customers

Get all customers visible to user

Get specific customer

Create a Customer

Update a Customer

Destroy an existing customer

Orders

Get all orders visible to user

Get specific order

Products

A note on `draft` vs `published` Products

Get all products visible to user

Get specific product

Create a Product

Note that valid values for the following attributes are:

Update a Product

Add a variety to existing product

Remove a variety from an existing product

Destroy an existing product

Publish a catalog

New to Fieldfolio?

Let's get started.

Seller API

Usage

Successful requests

Failed requests

Sending JSON data

Authentication

Catalogs

Get all catalogs visible to user

Get specific catalog

Customers

Get all customers visible to user

Get specific customer

Create a Customer

Update a Customer

Destroy an existing customer

Orders

Get all orders visible to user

Get specific order

Products

A note on draft vs published Products

Get all products visible to user

Get specific product

Create a Product

Note that valid values for the following attributes are:

Update a Product

Add a variety to existing product

Remove a variety from an existing product

Destroy an existing product

Publish a catalog

New to Fieldfolio?

Let's get started.

A note on `draft` vs `published` Products