Sign in

v1

latestOpenAPI 3.0.32026-07-13947245.3 KB
Goods records

Update an existing trader goods record

Update an existing TGP record

put/customs/traders/goods-profiles/{eori}/records/{recordId}

Path parameters

eoristring required

The traders' EORI number. The first 2 letters are the country code, like GB followed by 12 to 15 digits.

Example:GB123456789012

The traders' EORI number. The first 2 letters are the country code, like GB followed by 12 to 15 digits.

recordIdstring uuid required

ID of the record for the TGP Product in the TGP Core database (UUID)

Example:8ebb6b04-6ab0-4fe2-ad62-e6389a8a204f

ID of the record for the TGP Product in the TGP Core database (UUID)

Headers

Content-Typestring required
Example:application/json

Specifies the format of the request body, which must be JSON.

Acceptstring required
Example:application/vnd.hmrc.1.0+json

Specifies the response format and the version of the API to be used.

Authorizationstring required
Example:Bearer 59fc92c1cdf0b8ef1f138a702effdbd2

An OAuth 2.0 Bearer Token.

Request body

actorIdstring required

EORI number of the user making the change. This may be different to the eori. The first 2 letters are the country code, like GB or XI followed by 12 to 15 digits.

traderRefstring required

Unique product reference traders use to identify the goods. For example a Stock Keeping Unit (SKU) code. If the trader does not provide a traderRef, the front end should duplicate the goodsDescription field and pass this as traderRef.

comcodestring required

A code specific to goods that must be 6, 8, or 10 digits long. Only numeric values are allowed.

goodsDescriptionstring required

A description of the goods that the trader can choose. This field does not need to be unique.

countryOfOriginstring required

Country where the product came from. This is a char field with 2 letters in it as per ISO 3166 standards. You can also refer to CDS Appendix 13 Country codes for the Customs Declaration Service.

category1 | 2 | 3

To be retrieved using the Online Trade Tariff API. The category of the goods based on applicable restrictions, prohibitions or any exemptions the trader may hold.

supplementaryUnitnumber

Supplementary units are sometimes needed on H8 declarations and provide a quantity of goods in a specified unit of measurement.

measurementUnitstring

Measurement units define the required unit of measure when a supplementary unit is needed on an H8 declaration. Measurement units are defined in the Trade Tariff commodities API measurement documentation.

comcodeEffectiveFromDatestring date-time required

Date in the Online Tariff Tool (OTT) when authorised usage of a commodity code came into effect.

comcodeEffectiveToDatestring date-time

Date in the OTT when authorised usage of a commodity code expired or will expire.

Example request

{
  "actorId": "GB987654321098",
  "traderRef": "SKU123456",
  "comcode": "0810100000",
  "goodsDescription": "Bananas",
  "countryOfOrigin": "GB",
  "category": 2,
  "assessments": [
    {
      "assessmentId": "a06846e9a5f61fa4ecf2c4e3b23631fc",
      "primaryCategory": 1,
      "condition": {
        "type": "certificate",
        "conditionId": "Y923",
        "conditionDescription": "Products not considered as waste according to Regulation (EC) No 1013/2006 as retained in UK law",
        "conditionTraderText": "Excluded product"
      }
    }
  ],
  "supplementaryUnit": 13,
  "measurementUnit": "Kilograms",
  "comcodeEffectiveFromDate": "2023-01-01T00:00:00Z",
  "comcodeEffectiveToDate": "2028-01-01T00:00:00Z"
}

Response

OK; Request completed successfully

recordIdstring uuid required

ID of the record for the TGP Product in the TGP Core database (UUID)

eoristring required

The traders' EORI number. The first 2 letters are the country code, like GB followed by 12 to 15 digits.

actorIdstring required

EORI number of the user making the change. This may be different to the eori. The first 2 letters are the country code, like GB or XI followed by 12 to 15 digits.

traderRefstring required

Unique product reference traders use to identify the goods. For example a Stock Keeping Unit (SKU) code. If the trader does not provide a traderRef, the front end should duplicate the goodsDescription field and pass this as traderRef.

comcodestring required

A code specific to goods that must be 6, 8, or 10 digits long. Only numeric values are allowed.

adviceStatus'Not Requested' | 'Requested' | 'In progress' | 'Information Requested' | 'Advice request withdrawn' | 'Advice Provided' | 'Advice not provided' required

Indicates the advice status of a record if the trader has requested that HMRC review their commodity code.

goodsDescriptionstring required

A description of the goods that the trader can choose. This field does not need to be unique.

countryOfOriginstring required

Country where the product came from. This is a char field with 2 letters in it as per ISO 3166 standards. You can also refer to CDS Appendix 13 Country codes for the Customs Declaration Service.

category1 | 2 | 3

To be retrieved using the Online Trade Tariff API. The category of the goods based on applicable restrictions, prohibitions or any exemptions the trader may hold.

supplementaryUnitnumber

Supplementary units are sometimes needed on H8 declarations and provide a quantity of goods in a specified unit of measurement.

measurementUnitstring

Measurement units define the required unit of measure when a supplementary unit is needed on an H8 declaration. Measurement units are defined in the Trade Tariff commodities API measurement documentation.

comcodeEffectiveFromDatestring date-time required

Date in the Online Tariff Tool (OTT) when authorised usage of a commodity code came into effect.

comcodeEffectiveToDatestring date-time

Date in the OTT when authorised usage of a commodity code expired or will expire.

versioninteger required

Version of the TGP record.

activeboolean required

Status of the TGP record.

toReviewboolean required

The state of the record and if the trader needs to review it.

reviewReasonstring

The commodity code has expired. You'll need to change the commodity code and categorise the goods.

The country of origin is not valid. You'll need to change the country of origin and categorise the record.

The commodity code or restrictions have changed. You'll need to categorise the record.

HMRC have reviewed the record. The goods description is unclear. If you want to use this record on an IMMI, you'll need to amend the goods description.

HMRC have reviewed this record. The goods description does not have enough detail. If you want to use this record on an IMMI, you'll need to amend the goods description.

HMRC have reviewed this record. The commodity code and goods description do not match. If you want to use this record on an IMMI, you'll need to amend the commodity code and the goods description.

declarable'IMMI Ready' | 'Not Ready For IMMI' | 'Not Ready For Use' required

Status of TGP record for H8 declarations.

ukimsNumberstring required

The traders' UK Internal Market Scheme registration number.

nirmsNumberstring

The traders' Northern Ireland Retail Movement Scheme registration number.

niphlNumberstring

The traders' Northern Ireland Plant Health Label scheme registration number.

createdDateTimestring date-time required

Timestamp when the record was created.

updatedDateTimestring date-time required

Timestamp when the record was last updated.

Example response

{
  "recordId": "8ebb6b04-6ab0-4fe2-ad62-e6389a8a204f",
  "eori": "GB123456789012",
  "actorId": "GB987654321098",
  "traderRef": "SKU123456",
  "comcode": "0810100000",
  "adviceStatus": "Not Requested",
  "goodsDescription": "Bananas",
  "countryOfOrigin": "GB",
  "category": 2,
  "assessments": [
    {
      "assessmentId": "a06846e9a5f61fa4ecf2c4e3b23631fc",
      "primaryCategory": 1,
      "condition": {
        "type": "certificate",
        "conditionId": "Y923",
        "conditionDescription": "Products not considered as waste according to Regulation (EC) No 1013/2006 as retained in UK law",
        "conditionTraderText": "Excluded product"
      }
    }
  ],
  "supplementaryUnit": 13,
  "measurementUnit": "Kilograms",
  "comcodeEffectiveFromDate": "2023-01-01T00:00:00Z",
  "comcodeEffectiveToDate": "2028-01-01T00:00:00Z",
  "version": 1,
  "active": true,
  "toReview": true,
  "reviewReason": "The commodity code has expired. You'll need to change the commodity code and categorise the goods.",
  "declarable": "Not Ready For Use",
  "ukimsNumber": "XIUKIM47699357400020231115081800",
  "nirmsNumber": "RMS-GB-123456",
  "niphlNumber": "SP12345",
  "createdDateTime": "2023-01-01T00:00:00Z",
  "updatedDateTime": "2023-01-01T00:00:00Z"
}