Seller Business Locations API

Usage flow

Call the Create Location API to add a location and receive its xid.
Pass that xid in the seller_store_xid field when creating an invoice.
You can filter invoices by location and see the location in the invoice details.

List Locations API

Get the company's list of business locations.

GET

https://einvoice-api.sepay.vn/v1/business-locations

Success Response (200)

{
  "success": true,
  "data": [
    {
      "xid": "8f14e45f-ceea-4b6d-9c1a-2b3c4d5e6f70",
      "code": "CN01",
      "name": "Chi nhánh 1",
      "address": "12 Đường Ánh Sao, Quận 9, TP.HCM",
      "is_used": true,
      "is_active": true
    },
    {
      "xid": "3c59dc04-8e88-4506-b12a-9f3d1e7c5a21",
      "code": "HQ",
      "name": "Trụ sở chính",
      "address": "1 Đường Ban Mai, Quận 9, TP.HCM",
      "is_used": false,
      "is_active": true
    }
  ]
}

successboolean

dataarray<object>

curl --request GET \
  --url https://einvoice-api.sepay.vn/v1/business-locations \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Create Location API

Add a new location to the catalog. A new location starts enabled (is_active=true).

POST

https://einvoice-api.sepay.vn/v1/business-locations/create

codestringrequired

Business location code, max 50 characters. A fixed identifier - set at creation and cannot be changed. Unique within the company, duplicates return SELLER_STORE_DUPLICATE_CODE.

namestringrequired

Business location name per the business registration certificate, max 400 characters. Unique within the company, duplicates return SELLER_STORE_DUPLICATE_NAME.

addressstringrequired

Business location address, max 255 characters. Unique within the company, duplicates return SELLER_STORE_DUPLICATE_ADDRESS.

Success Response (201)

{
  "success": true,
  "data": {
    "xid": "b6d767d2-f8ed-4c1b-9a2e-7f5c3d1a8b40",
    "code": "CN02",
    "name": "Chi nhánh 2",
    "address": "34 Đường Hoa Nắng, Quận 7, TP.HCM",
    "is_used": false,
    "is_active": true
  }
}

successboolean

dataobject

curl --request POST \
  --url https://einvoice-api.sepay.vn/v1/business-locations/create \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"code":"CN02","name":"Chi nhánh 2","address":"34 Đường Hoa Nắng, Quận 7, TP.HCM"}'

Update Location API

Edit a location's name or address, or activate/deactivate it. A location already used on invoices can still be edited, and already issued invoices are not affected.

POST

https://einvoice-api.sepay.vn/v1/business-locations/update

xidstringrequired

The xid (a UUID) of the location to update, from the list API.

namestring

New name, max 400 characters, unique within the company. Optional - send it only to change the name, leaving it out keeps the current name. Sending it blank is rejected.

addressstring

New address, max 255 characters, unique within the company. Optional - send it only to change the address, leaving it out keeps the current address. Sending it blank is rejected.

is_activeboolean

Activate (true) or deactivate (false) the location. A deactivated location cannot be used on new invoices, but invoices already linked to it can still be queried.

Success Response (200)

{
  "success": true,
  "data": {
    "xid": "b6d767d2-f8ed-4c1b-9a2e-7f5c3d1a8b40",
    "code": "CN02",
    "name": "Chi nhánh 2 - Quận 3",
    "address": "58 Đường Trăng Thanh, Quận 3, TP.HCM",
    "is_used": false,
    "is_active": true
  }
}

curl --request POST \
  --url https://einvoice-api.sepay.vn/v1/business-locations/update \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"xid":"b6d767d2-f8ed-4c1b-9a2e-7f5c3d1a8b40","name":"Chi nhánh 2 - Quận 3","address":"58 Đường Trăng Thanh, Quận 3, TP.HCM","is_active":false}'

Delete Location API

Delete a location from the catalog. Only locations that have never been used on an invoice can be deleted.

POST

https://einvoice-api.sepay.vn/v1/business-locations/delete

xidstringrequired

The xid (a UUID) of the location to delete, from the list API. Only a location never used on an invoice can be deleted - deactivate a used one (is_active=false) instead.

Success Response (200)

{
  "success": true,
  "message": "Đã xóa địa điểm kinh doanh người bán"
}

curl --request POST \
  --url https://einvoice-api.sepay.vn/v1/business-locations/delete \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"xid":"b6d767d2-f8ed-4c1b-9a2e-7f5c3d1a8b40"}'

Error Handling

The location endpoints return errors in the shape { "success": false, "error": { "code": "...", "message": "..." } }.

401UNAUTHORIZED

Missing or invalid Bearer token.

422VALIDATION_ERROR

Missing required field, exceeds length limit, or nothing to update.

422SELLER_STORE_DUPLICATE_CODE

The location code already exists in the company (create only).

422SELLER_STORE_DUPLICATE_NAME

The location name already exists in the company.

422SELLER_STORE_DUPLICATE_ADDRESS

The address already exists in the company catalog.

404SELLER_STORE_NOT_FOUND

The location does not exist or does not belong to your account (update/delete).

409SELLER_STORE_IN_USE

The location has been used to issue invoices and cannot be deleted - deactivate it (is_active=false) instead.

405METHOD_NOT_ALLOWED

Wrong HTTP method for the endpoint.

500INTERNAL_ERROR

An error occurred, please contact SePay for support.

About is_used and is_active

is_used=true: the location has been used on at least one invoice. It cannot be deleted, but its name, address, and is_active toggle can still be edited.
is_active=false: the location is deactivated and cannot be selected for new invoices (the invoice creation API returns 400 SELLER_STORE_INACTIVE), but invoices already linked to it can still be filtered and queried.

Next Steps

Once you have the location xid, you can:

Create an invoice - Pass seller_store_xid to send the location code and name to the invoice.
List invoices - Filter invoices by seller_store_xid.