Integrations

Product integration

Product-related integration endpoints

Base URL: https://api.miridia.io. Read Authentication and Conventions before you call these operations.

Method	Path	Operation
POST	`/api/v1/integration/products`	Create product
PUT	`/api/v1/integration/products`	Update product

Create product

POST/api/v1/integration/products

Access. Send a bearer token or an API key. The caller needs the Products modify permission.

Request body

Send JSON with the shape CreateProductIntegrationCommand. The incoming request to import a product family from an external integration. One endpoint covers all cases: a single "default variant" (one variant, no group), a multi-variant family (the backend materializes a group), or an incremental sync that attaches a variant to an existing family.

Field	Type	Required	Description
`group`	`IntegrationProductGroupRequest`	No
`variants`	`IntegrationProductVariantRequest[]`	Yes

Response

200. Returns a SingleResult envelope. The data field is ProductFamilyResponse.

Request

curl -X POST "https://api.miridia.io/api/v1/integration/products" \
  -H "Authorization: Bearer $MIRIDIA_TOKEN" \
  -H "X-Business-Id: $MIRIDIA_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "group": {
    "externalGroupId": "string",
    "name": "string",
    "optionAxes": [
      "string"
    ]
  },
  "variants": [
    {
      "product": {},
      "context": {},
      "optionValues": {
        "key": "string"
      },
      "isPrimary": true
    }
  ]
}'

Response

{
  "message": "string",
  "messages": [
    {
      "title": "string",
      "message": "string",
      "level": "Standard",
      "icon": "SyncAlert",
      "code": "string"
    }
  ],
  "data": {
    "group": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "string",
      "description": "string",
      "optionAxes": [
        "string"
      ],
      "primaryProductId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "externalGroupId": "string",
      "members": [
        {}
      ],
      "dateCreated": "2026-09-29T08:00:00Z"
    },
    "products": [
      {}
    ]
  },
  "statusCode": "OK",
  "canRead": true,
  "canEdit": true,
  "canDelete": true
}

Update product

PUT/api/v1/integration/products

Access. Send a bearer token or an API key. The caller needs the Products modify permission.

Request body

Send JSON with the shape UpdateProductIntegrationCommand. Updates the sync state of an existing product integration link. Detects price/quantity deltas, records observed values, and. When PriceSyncEnabled is configured on the provider. Upserts the price into the channel's assigned price list. NEVER writes to canonical price history directly.

Field	Type	Required	Description
`product`	`CreateProductRequest`	Yes
`context`	`IntegrationContextRequest`	Yes

Response

200. Returns a SingleResult envelope. The data field is ProductResponse.

Request

curl -X PUT "https://api.miridia.io/api/v1/integration/products" \
  -H "Authorization: Bearer $MIRIDIA_TOKEN" \
  -H "X-Business-Id: $MIRIDIA_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "product": {
    "sku": "string",
    "title": "string",
    "description": "string",
    "body": "string",
    "price": {
      "subTotal": 0,
      "totalPrice": 0,
      "totalTax": 0,
      "totalDiscount": 0,
      "discount": 0,
      "discountType": "Percentage",
      "taxIncluded": true,
      "taxRate": 0,
      "taxType": "Sales"
    },
    "geometry": {
      "weight": 0,
      "width": 0,
      "length": 0,
      "height": 0,
      "lengthType": "Centimeter",
      "weightType": "Kilogram"
    },
    "productType": "FinishedGood",
    "status": "Active",
    "unit": "Each",
    "barcode": "string",
    "upc": "string",
    "ean": "string",
    "mpn": "string",
    "purchasable": true,
    "isSellable": true,
    "isPurchasable": true,
    "isTaxable": true,
    "requiresShipping": true,
    "tags": [
      "string"
    ],
    "imageIds": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ],
    "imageUrls": [
      "string"
    ],
    "defaultImageUrl": "string",
    "groupAssignment": {
      "groupId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "optionValues": {
        "key": "string"
      },
      "position": 0
    },
    "supplierId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "dateCreated": "2026-09-29T08:00:00Z",
    "metadata": {
      "key": "string"
    }
  },
  "context": {
    "configuredProviderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "id": "string",
    "idType": "Long",
    "content": "string",
    "metadata": {
      "key": "string"
    },
    "reportedQuantity": 0,
    "dateCreated": "2026-09-29T08:00:00Z"
  }
}'

Models

The operations on this page use these object types. Select a type to see its fields.

ActionMessage

Action messages surface to the API and provide more detailed user feedback for handled exceptions or errors.

Field	Type	Description
`title`	`string`
`message`	`string`
`level`	`enum NotificationLevel`	One of: `Standard`, `Info`, `Warning`, `Error`, `Success`, `Recommendation`.
`icon`	`enum MdiIcon`	One of: `None`, `SyncAlert`, `Autorenew`, `Check`, `CheckMarkedCircle`, `AlertCircle`, `TruckDeliveryOutline`, `TruckFastOutline`, `PackageCheck`, `Warehouse`, `SwapHorizontal`, `AccountCheck`, `AccountRemove`, `AccountCancel`, `Delete`.
`code`	`string`	The Notification code / Suggestion code for this suggestion

AddressResponse

Field	Type	Description
`id`	`string (uuid)`
`placeId`	`string`
`name`	`string`
`website`	`string`
`fullAddress`	`string`
`street`	`string`
`suburb`	`string`
`city`	`string`
`country`	`string`
`postcode`	`string`
`unit`	`string`
`number`	`string`
`province`	`string`
`latitude`	`number (double)`
`longitude`	`number (double)`

ContactResponse

Field	Type	Description
`id`	`string (uuid)`
`title`	`string`
`description`	`string`
`firstName`	`string`
`lastName`	`string`
`email`	`string`
`phoneNumber`	`string`
`mobileNumber`	`string`

CreateProductPriceRequest

Field	Type	Description
`subTotal`	`number (double)`	Limits: minimum 0.
`totalPrice`	`number (double)`	Limits: minimum 0.
`totalTax`	`number (double)`	Limits: minimum 0.
`totalDiscount`	`number (double)`	Limits: minimum 0.
`discount`	`number (double)`	Limits: minimum 0.
`discountType`	`enum DiscountType`	One of: `None`, `Percentage`, `FixedValue`.
`taxIncluded`	`boolean`
`taxRate`	`number (double)`	Limits: minimum 0, maximum 100.
`taxType`	`enum TaxType`	One of: `None`, `Sales`, `Vat`, `Gst`, `Pst`, `Hst`, `Qst`, `Ist`, `Ust`, `Cst`.

CreateProductRequest

Field	Type	Description
`sku`	`string`
`title`	`string`	Limits: maximum 100 characters.
`description`	`string`	Provides a summary of the product Limits: maximum 1000 characters.
`body`	`string`
`price`	`CreateProductPriceRequest`
`geometry`	`ProductDimensionRequest`
`productType`	`enum ProductType`	One of: `FinishedGood`, `RawMaterial`, `Component`, `Consumable`, `Service`.
`status`	`enum ProductStatus`	One of: `Active`, `Inactive`, `Discontinued`.
`unit`	`enum UnitOfMeasure`	One of: `Each`, `Kilogram`, `Gram`, `Litre`, `Millilitre`, `Metre`, `Centimetre`, `SquareMetre`, `CubicMetre`, `Pair`, `Pack`, `Box`, `Roll`, `Sheet`.
`barcode`	`string`
`upc`	`string`
`ean`	`string`
`mpn`	`string`
`purchasable`	`boolean`
`isSellable`	`boolean`
`isPurchasable`	`boolean`
`isTaxable`	`boolean`
`requiresShipping`	`boolean`
`tags`	`string[]`
`imageIds`	`string (uuid)[]`	Images which have been uploaded via the FileController.
`imageUrls`	`string[]`
`defaultImageUrl`	`string`
`groupAssignment`	`ProductGroupAssignmentRequest`
`supplierId`	`string (uuid)`
`dateCreated`	`string (date-time)`	When the product was created. Optional; defaults to now. Lets seeded/synthetic catalogs show products appearing over time rather than all on seed day.
`metadata`	`map<string, string>`

CurrencyResponse

Field	Type	Description
`iso4217`	`string`
`utf8Symbol`	`string`
`currencyCode`	`enum CurrencyCode`	One of: `Invalid`, `Eur`, `Usd`, `Gbp`, `Zar`, `Zmw`.

DimensionPresetResponse

Field	Type	Description
`id`	`string (uuid)`
`vendor`	`string`	Limits: maximum 100 characters.
`fulfillmentType`	`enum FulfillmentType`	One of: `Unknown`, `Package`, `Pallet`, `Container`, `Miscellaneous`.
`title`	`string`	Limits: maximum 200 characters.
`weight`	`number (double)`	The weight property acts as a limit for this specific box size.
`length`	`number (double)`
`width`	`number (double)`
`height`	`number (double)`
`defaultOption`	`boolean`	every business can have one package size preset set as the default option
`lengthType`	`enum LengthType`	One of: `Unknown`, `Centimeter`, `Meter`, `Inch`, `Foot`.
`weightType`	`enum WeightType`	One of: `Unknown`, `Kilogram`, `Tonne`, `Pound`, `Stone`, `UsTon`, `ImperialTon`, `Gram`.
`countryCode`	`enum CountryCode`	One of: `Invalid`, `Global`, `FallbackZa`, `Be`, `De`, `Lu`, `Nl`, `Za`, `Zw`, `Gb`, `Us`, `Zm`.
`dimensionType`	`GeometryFieldSymbol`

GeometryAndCountryMetadata

Field	Type	Description
`currencyCode`	`enum CurrencyCode`	One of: `Invalid`, `Eur`, `Usd`, `Gbp`, `Zar`, `Zmw`.
`countryCode`	`enum CountryCode`	One of: `Invalid`, `Global`, `FallbackZa`, `Be`, `De`, `Lu`, `Nl`, `Za`, `Zw`, `Gb`, `Us`, `Zm`.
`weightType`	`enum WeightType`	One of: `Unknown`, `Kilogram`, `Tonne`, `Pound`, `Stone`, `UsTon`, `ImperialTon`, `Gram`.
`lengthType`	`enum LengthType`	One of: `Unknown`, `Centimeter`, `Meter`, `Inch`, `Foot`.

GeometryFieldSymbol

Field	Type	Description
`weightType`	`enum WeightType`	One of: `Unknown`, `Kilogram`, `Tonne`, `Pound`, `Stone`, `UsTon`, `ImperialTon`, `Gram`.
`lengthType`	`enum LengthType`	One of: `Unknown`, `Centimeter`, `Meter`, `Inch`, `Foot`.
`lengthSymbol`	`string`
`weightSymbol`	`string`

IntegrationContextRequest

Field	Type	Description
`configuredProviderId`	`string (uuid)`
`id`	`string`
`idType`	`enum UidType`	One of: `Unknown`, `Long`, `Guid`, `String`.
`content`	`string`	Can be used to store the raw data received from the external system. Maps to SerializedData...
`metadata`	`map<string, string>`	Additional metadata related to the integration object.
`reportedQuantity`	`integer (int32)`	The available-to-sell quantity the provider reports for this product. Null when the provider does not report a quantity.
`dateCreated`	`string (date-time)`

IntegrationProductGroupRequest

The umbrella family an integration import belongs to. A Miridia product group maps to the provider's product (e.g. a Shopify Product); each variant maps to a member product. Null when the provider has no family concept (a single "default variant" import).

Field	Type	Description
`externalGroupId`	`string`	The provider's family/product identifier (e.g. Shopify product GID). Drives idempotent re-sync and promotion.
`name`	`string`	Display name for the family. Falls back to the primary variant's title when omitted.
`optionAxes`	`string[]`	The option axes the family varies along, e.g. ["Size", "Colour"].

IntegrationProductVariantRequest

One variant in a family import: the product to create/attach, its integration context, and its per-axis values. Equivalent to the old single-product integration body plus grouping metadata.

Field	Type	Description
`product`	`CreateProductRequest`
`context`	`IntegrationContextRequest`
`optionValues`	`map<string, string>`	Per-axis values for this variant against the family's option axes, e.g. {"Size":"1L"}.
`isPrimary`	`boolean`	Whether this variant is the family primary (the umbrella's representative member).

MetadataFileAttachment

Not quite as complete as the normal FileAttachment aggregate.

Field	Type	Description
`id`	`string (uuid)`
`type`	`enum MetadataAttachmentType`	One of: `File`, `Link`.
`fileAttachmentId`	`string (uuid)`	Left as `Guid.Empty` for `Link` entries.
`title`	`string`
`url`	`string`
`contentType`	`string`
`description`	`string`

PrimitiveIntegrationProviderResponse

Field	Type	Description
`configuredProviderId`	`string (uuid)`
`id`	`integer (int32)`
`title`	`string`
`description`	`string`
`logoUrl`	`string`

ProductCategoryPrimitive

Field	Type	Description
`category`	`string`

ProductDimensionRequest

Field	Type	Description
`weight`	`number (double)`	Limits: minimum 0.
`width`	`number (double)`	Limits: minimum 0.
`length`	`number (double)`	Limits: minimum 0.
`height`	`number (double)`	Limits: minimum 0.
`lengthType`	`enum LengthType`	One of: `Unknown`, `Centimeter`, `Meter`, `Inch`, `Foot`.
`weightType`	`enum WeightType`	One of: `Unknown`, `Kilogram`, `Tonne`, `Pound`, `Stone`, `UsTon`, `ImperialTon`, `Gram`.

ProductFamilyResponse

Response for a family import. group is null when fewer than two members exist (a single "default variant" stays ungrouped). Each ProductResponse carries its Integrations[].Id so an order sync can reference its line items by ProductIntegrationId.

Field	Type	Description
`group`	`ProductGroupResponse`
`products`	`ProductResponse[]`

ProductGeometryFieldsResponse

Field	Type	Description
`weight`	`number (double)`
`width`	`number (double)`
`length`	`number (double)`
`height`	`number (double)`
`lengthType`	`enum LengthType`	One of: `Unknown`, `Centimeter`, `Meter`, `Inch`, `Foot`.
`weightType`	`enum WeightType`	One of: `Unknown`, `Kilogram`, `Tonne`, `Pound`, `Stone`, `UsTon`, `ImperialTon`, `Gram`.
`weightSymbol`	`string`
`lengthSymbol`	`string`
`fulfillmentType`	`enum FulfillmentType`	One of: `Unknown`, `Package`, `Pallet`, `Container`, `Miscellaneous`.
`title`	`string`
`geometrySymbol`	`GeometryFieldSymbol`

ProductGroupAssignmentRequest

Create-time membership of a product in an existing product group.

Field	Type	Description
`groupId`	`string (uuid)`
`optionValues`	`map<string, string>`	Per-axis values for this member, e.g. {"Pack Size": "4-pack"}.
`position`	`integer (int32)`	Display order within the group; appended (0) when omitted.

ProductGroupMemberResponse

Field	Type	Description
`productId`	`string (uuid)`
`sku`	`string`
`title`	`string`
`totalAvailableQuantity`	`number (double)`
`currentPrice`	`ProductPriceDetailsResponse`
`optionValues`	`map<string, string>`
`position`	`integer (int32)`
`isPrimary`	`boolean`

ProductGroupResponse

Field	Type	Description
`id`	`string (uuid)`
`name`	`string`
`description`	`string`
`optionAxes`	`string[]`
`primaryProductId`	`string (uuid)`
`externalGroupId`	`string`	Null = merchant-owned.
`members`	`ProductGroupMemberResponse[]`
`dateCreated`	`string (date-time)`

ProductGroupSummaryResponse

Catalog-card summary of a product group (variant family): the umbrella name and how many products it contains. See group.

Field	Type	Description
`id`	`string (uuid)`
`name`	`string`
`variantCount`	`integer (int32)`

ProductIntegrationProviderResponse

Field	Type	Description
`provider`	`PrimitiveIntegrationProviderResponse`
`id`	`string (uuid)`	Represents the product integration id.
`integrationId`	`string`	The composite integration id in it's original form represented as a string. Refer to ProductService::GetProductResponse()
`product`	`ProductResponse`

ProductPriceDetailsResponse

Field	Type	Description
`subTotal`	`number (double)`
`totalPrice`	`number (double)`
`totalTax`	`number (double)`
`totalDiscount`	`number (double)`
`discount`	`number (double)`
`discountType`	`enum DiscountType`	One of: `None`, `Percentage`, `FixedValue`.
`taxIncluded`	`boolean`
`taxRate`	`number (double)`
`taxType`	`enum TaxType`	One of: `None`, `Sales`, `Vat`, `Gst`, `Pst`, `Hst`, `Qst`, `Ist`, `Ust`, `Cst`.
`currency`	`CurrencyResponse`
`id`	`string (uuid)`
`purchasable`	`boolean`
`priceType`	`enum PriceType`	One of: `Selling`, `Purchase`, `Cost`.
`source`	`enum PriceSource`	One of: `Manual`, `SupplierUpdate`, `Import`, `Sync`, `Migration`.
`notes`	`string`
`effectiveDate`	`string (date-time)`
`currencyMetadata`	`CurrencyResponse`
`priceUnit`	`enum UnitOfMeasure`	One of: `Each`, `Kilogram`, `Gram`, `Litre`, `Millilitre`, `Metre`, `Centimetre`, `SquareMetre`, `CubicMetre`, `Pair`, `Pack`, `Box`, `Roll`, `Sheet`.
`pricePackQuantity`	`number (double)`
`pricePerUnit`	`number (double)`
`basis`	`enum PriceResolutionBasis`	One of: `FixedItem`, `PeggedItem`, `ListRule`.
`adjustmentType`	`enum PriceAdjustmentType`	One of: `Percentage`, `Amount`.
`adjustmentValue`	`number (double)`

ProductResponse

Field	Type	Description
`id`	`string (uuid)`
`code`	`string`
`sku`	`string`
`barcode`	`string`
`upc`	`string`
`ean`	`string`
`mpn`	`string`
`title`	`string`
`description`	`string`
`body`	`string`
`productLink`	`string`
`productType`	`enum ProductType`	One of: `FinishedGood`, `RawMaterial`, `Component`, `Consumable`, `Service`.
`status`	`enum ProductStatus`	One of: `Active`, `Inactive`, `Discontinued`.
`unit`	`enum UnitOfMeasure`	One of: `Each`, `Kilogram`, `Gram`, `Litre`, `Millilitre`, `Metre`, `Centimetre`, `SquareMetre`, `CubicMetre`, `Pair`, `Pack`, `Box`, `Roll`, `Sheet`.
`purchasable`	`boolean`
`isSellable`	`boolean`
`isPurchasable`	`boolean`
`isTaxable`	`boolean`
`requiresShipping`	`boolean`
`totalAvailableQuantity`	`number (double)`	Available stock derived from the inventory ledger: the sum of (on-hand − reserved) across the product's inventory records at all locations.
`totalSold`	`number (double)`
`totalSoldValue`	`number (double)`
`onSale`	`boolean`
`currentPrice`	`ProductPriceDetailsResponse`
`traces`	`ActionMessage[]`	Get the historical view of changes for this object
`defaultImage`	`MetadataFileAttachment`
`images`	`MetadataFileAttachment[]`
`attachments`	`MetadataFileAttachment[]`
`geometry`	`ProductGeometryFieldsResponse`
`integrations`	`ProductIntegrationProviderResponse[]`
`locale`	`SymbolicLocaleMetadata`
`dimensionPreset`	`DimensionPresetResponse`
`dimensionPresets`	`DimensionPresetResponse[]`
`categories`	`ProductCategoryPrimitive[]`
`supplier`	`SupplierResponse`
`group`	`ProductGroupSummaryResponse`
`tags`	`string[]`
`hasRating`	`boolean`
`rating`	`number (double)`
`metadata`	`map<string, string>`
`dateCreated`	`string (date-time)`

SupplierResponse

Field	Type	Description
`id`	`string (uuid)`
`title`	`string`
`description`	`string`
`contact`	`ContactResponse`
`addressId`	`string (uuid)`	Reference to the supplier's origin address (`business_addresses`), if set.
`address`	`AddressResponse`
`paymentTerms`	`string`	Free-text payment terms (e.g. "Net 30"). Display-only.
`defaultLeadTimeDays`	`integer (int32)`	Fallback lead time in days for suppliers with no purchase-order history yet.
`code`	`string`	Optional free-text internal reference code for the supplier (e.g. "SUP-001"). Display-only.
`defaultCurrency`	`enum CurrencyCode`	One of: `Invalid`, `Eur`, `Usd`, `Gbp`, `Zar`, `Zmw`.

SymbolicLocaleMetadata

Field	Type	Description
`currency`	`string`
`country`	`string`
`weight`	`string`
`length`	`string`
`businessDefaultTypes`	`GeometryAndCountryMetadata`

Order integration

This controller handles order-related integration endpoints.

Shipment integration

The shipment integration operations of the Core API.