Data Requirements and Setup

Customer Identity

• Domestic FE uses customer metafield hacienda.structured_cedula.
• Optional domestic activity code uses hacienda.structured_ciiu.
• Export invoices use customer metafield ticosync.tax_id, shown in Shopify as Tax ID/Passport.

Export Identity Fallback Order

1. ticosync.tax_id
2. Billing phone
3. Shipping phone
4. Order phone
5. Customer phone

Tax ID/Passport is cleaned to letters and numbers only. Phone fallback is cleaned to digits only.

CABYS

• TicoSync looks for hacienda.structured_cabys on the variant first.
• If the variant does not have it, TicoSync falls back to the product.
• Missing CABYS can cause Hacienda rejections or incorrect tax classification.

HS Code for Export

• Export goods lines use Shopify's standard customs HS code from the variant inventory item.
• If Shopify has a destination-country specific customs code, TicoSync prefers that value.
• TicoSync pads short HS code values with zeros on the right to produce the Partida Arancelaria sent in export XML.

Shop-Level Config

• Issuer identity, activity code, signing credentials, PDF header text, and related Hacienda settings are managed in the Configs page.
• International Optional Header Text is used on export PDFs instead of the normal Optional PDF Header Text.