Updating resources

How to update a resource via API

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.

Authentication

Examples

Updating attributes

Request

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."
    }
  }
}'

Response

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",
      "organization_id": "wBstRPzLrk",
      "trace_id": "7d4e1b8c2f5a9d3e6b0c8f1a5d2e9b4f7c3a6d0e8b1f5c2a7d4e1b8c3f6a9d2e"
    }  
  },
  "meta": {
    "mode": "test",
    "organization_id": "wBstRPzLrk",
    "trace_id": "7d4e1b8c2f5a9d3e6b0c8f1a5d2e9b4f7c3a6d0e8b1f5c2a7d4e1b8c3f6a9d2e"
  }
}

Updating relationships

Request

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

Response

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",
      "organization_id": "wBstRPzLrk",
      "trace_id": "f2a8c5e1b7d3f9a4c6e2b8d5f1a7c3e9b4d0f6a2c8e5b1d7f3a9c4e0b6d2f8a5"
    }  
  },
  "meta": {
    "mode": "test",
    "organization_id": "wBstRPzLrk",
    "trace_id": "f2a8c5e1b7d3f9a4c6e2b8d5f1a7c3e9b4d0f6a2c8e5b1d7f3a9c4e0b6d2f8a5"
  }
}

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.

Request

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

Response

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": "[e-mail]",
      "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",
      "trace_id": "b3e7d1f5a9c2b8e4d0f6a3c7e1b5d9f2a6c0e8b4d2f7a1c5e3b9d6f0a4c8e2b7"
    }
  },
  "meta": {
    "mode": "test",
    "organization_id": "EnAvaFOrRe",
    "trace_id": "b3e7d1f5a9c2b8e4d0f6a3c7e1b5d9f2a6c0e8b4d2f7a1c5e3b9d6f0a4c8e2b7"
  }
}