Introducing our brand new Rules Engine —
Read the docs
LogoLogo
Core APIOther APIsChangelog
Getting started
Getting started
  • Welcome to Commerce Layer
    • Guided setup
    • Manual configuration
  • API specification
  • API credentials
  • Authentication
    • Client credentials
    • Password
    • Authorization code
    • Refresh token
    • JWT bearer
    • Revoking a token
  • Roles and permissions
  • Fetching resources
  • Fetching relationships
  • Including associations
  • Sparse fieldsets
  • Sorting results
  • Pagination
  • Filtering data
  • Creating resources
  • Updating resources
  • Tagging resources
  • Deleting resources
  • Importing resources
  • Exporting resources
  • Cleaning up resources
  • External resources
    • External order validation
    • External prices
    • External shipping costs
    • External payment gateways
    • External promotions
    • External tax calculators
  • Rate limits
  • Handling errors
  • Real-time webhooks
  • Callbacks security
On this page

Updating resources

How to update a resource via API

PreviousCreating resourcesNextTagging resources

Last updated 10 months ago

You can update a resource by sending a PATCH request to the resources endpoint, with a JSON payload.

The Content-Type header must be application/vnd.api+json.

You can get the list of arguments, with type and examples from the documentation of each resource.

Examples

Updating attributes

The following request updates the description of an existing SKU:

curl -g -X PATCH \
  'https://yourdomain.commercelayer.io/api/skus/xYZkjABcde' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
  "data": {
    "type": "skus",
    "id": "xYZkjABcde",
    "attributes": {
      "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."
    }
  }
}'

On success, the API responds with a 200 OK status code, returning the updated resource object:

{
  "data": {
    "id": "xYZkjABcde",
    "type": "skus",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/skus/xYZkjABcde"
    },
      "attributes": {
        "code": "TSHIRTMM000000FFFFFFXLXX",
        "name": "Men's Black T-shirt with White Logo (XL)",
        "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
        "image_url": null,
        "tag_names": "",
        "pieces_per_pack": null,
        "weight": null,
        "unit_of_weight": null,
        "hs_tariff_number": null,
        "do_not_ship": false,
        "do_not_track": false,
        "created_at": "2018-01-01T12:00:00.000Z",
        "updated_at": "2018-01-01T12:00:00.000Z",
        "reference": null,
        "metadata": {}
      },
      "relationships": {
        "shipping_category": {
          "links": {...}
        },
        "prices": {
          "links": {...}
        },
        "stock_items": {
          "links": {...}
        },
        "delivery_lead_times": {
          "links": {...}
        },
        "sku_options": {
          "links": {...}
        }
    },
    "meta": {
      "mode": "test"
    }  
  }
}

Updating relationships

The following request changes the shipping category of an existing SKU:

curl -g -X PATCH \
  'https://yourdomain.commercelayer.io/api/skus/xYZkjABcde' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
  "data": {
    "type": "skus",
    "id": "xYZkjABcde",
    "relationships": {
      "shipping_category": {
        "data": {
          "type": "shipping_categories",
          "id": "ywMJmFPBWA"
        }
      }
    }
  }
}'

On success, the API responds with a 200 OK status code, returning the updated resource object:

{
  "data": {
    "id": "xYZkjABcde",
    "type": "skus",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/skus/xYZkjABcde"
    },
      "attributes": {
        "code": "TSHIRTMM000000FFFFFFXLXX",
        "name": "Men's Black T-shirt with White Logo (XL)",
        "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
        "image_url": null,
        "tag_names": "",
        "pieces_per_pack": null,
        "weight": null,
        "unit_of_weight": null,
        "hs_tariff_number": null,
        "do_not_ship": false,
        "do_not_track": false,
        "created_at": "2018-01-01T12:00:00.000Z",
        "updated_at": "2018-01-01T12:00:00.000Z",
        "reference": null,
        "metadata": {}
      },
      "relationships": {
        "shipping_category": {
          "links": {...}
        },
        "prices": {
          "links": {...}
        },
        "stock_items": {
          "links": {...}
        },
        "delivery_lead_times": {
          "links": {...}
        },
        "sku_options": {
          "links": {...}
        }
    },
    "meta": {
      "mode": "test"
    }  
  }
}

Removing relationships

If a relationship is optional for the creation of a resource, it can be removed by sending PATCH request with the data object set as null.

The following request removes a customer from a customer group:

curl -g -X PATCH \
  'https://yourdomain.commercelayer.io/api/customers/bQWpdhWxVk' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
  "data": {
    "type": "customers",
    "id": "bQWpdhWxVk",
    "relationships": {
      "customer_group": {
        "data": null
      }
    }
  }
}'

On success, the API responds with a 200 OK status code, returning the updated resource object:

{
  "data": {
    "id": "bQWpdhWxVk",
    "type": "customers",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/customers/bQWpdhWxVk"
    },
    "attributes": {
      "email": "john@example.com",
      "status": "acquired",
      "has_password": true,
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": "",
      "reference_origin": null,
      "metadata": {}
    },
    "relationships": {
      "customer_group": {
        "links": { ... }
      },
      "customer_addresses": {
        "links": { ... }
      },
      "customer_payment_sources": {
        "links": { ... }
      },
      "customer_subscriptions": {
        "links": { ... }
      },
      "orders": {
        "links": { ... }
      },
      "order_subscriptions": {
        "links": { ... }
      },
      "returns": {
        "links": { ... }
      },
      "sku_lists": {
        "links": { ... }
      },
      "attachments": {
        "links": { ... }
      },
      "events": {
        "links": { ... }
      }
    },
    "meta": {
      "mode": "test",
      "organization_id": "EnAvaFOrRe"
    }
  }
}
Authentication