Overview
The Linnworks integration provides a set of ready-made functions you can call when building mappings. They handle common lookups and conversions against your Linnworks account and your iPaaS.com data. For example, they can turn a postal service name into the ID Linnworks expects, or turn an iPaaS.com location ID into a location name, so you don't have to build that logic yourself.
Where you can use these functions
These functions are available anywhere you write a formula for the Linnworks integration:
Dynamic Formula mappings: where a destination field's value is produced by a formula rather than mapped directly from a source field.
Mapping collection filters: where a formula decides whether a record should be processed.
Error filters: a mapping collection's error filter, which sits alongside its collection filter. When the error filter's formula resolves to true, the transfer raises an error that is held in the Error Logs for review and is not retried automatically.
Translation collections: where a translation entry uses a formula as its source value.
How to use them
Call a function by name and pass the values it needs in parentheses. For example:
await GetPostalServiceIdByNameAsync(PostalServiceName).Each function's signature shows its name, the parameters it accepts (with their types), and the type of value it returns. Use it as the reference for exactly how to call the function.
Function names and formula syntax are case-sensitive, so type each name exactly as shown. Whether the values a function matches are treated as case-sensitive varies by function, and is called out in the relevant parameter's description.
Every Linnworks function returns a
Task, so it is asynchronous and must be called withawait, as shown in each How to call it example.Each function runs at sync time, against the data in your connected Linnworks account and your iPaaS.com subscription.
When a lookup finds no match, the function returns an empty value (
nullfor the text-returning functions, or an empty list). Build your formula so it behaves correctly when that happens, for example by supplying a fallback value.
The functions are grouped below by the area of the integration they support.
Products
Use these when mapping product data to or from Linnworks.
GetLinnworksCategoryIdByNameAsync
What it does: Looks up a Linnworks category by its name and returns that category's Linnworks category ID. Returns null if no category matches.
Signature: Task<string> GetLinnworksCategoryIdByNameAsync(string categoryName)
How to call it: await GetLinnworksCategoryIdByNameAsync(categoryName)
Parameter | Type | Required | Default | Description |
categoryName |
| Yes | N/A | The name of the Linnworks category to look up, for example |
Returns: string. The matching Linnworks category ID, or null if no category matches.
Example: "Electronics" returns "12345".
When to use it: When creating or updating a Linnworks product and you need the Linnworks category ID that corresponds to a category name in your source data.
GetiPaaSProductBySkuAsync
What it does: Retrieves the iPaaS.com product records that match one or more SKUs. If a SKU has no matching product, its variant is looked up instead. Returns an empty list if nothing matches.
Signature: Task<List<GetAllResponseProduct>> GetiPaaSProductBySkuAsync(object skus)
How to call it: await GetiPaaSProductBySkuAsync(skus)
Parameter | Type | Required | Default | Description |
skus |
| Yes | N/A | A single SKU (a |
Returns: List<GetAllResponseProduct>. The matching iPaaS.com product (or variant) records. The list is empty if no SKUs match.
Example: "ABC123", or a list such as "ABC123", "XYZ999", returns the iPaaS.com product or variant records for those SKUs.
When to use it: During order or inventory processing when you need iPaaS.com product details for one or more SKUs, for example to validate an order line or resolve product information before mapping.
Inventory and Locations
Use these when mapping product inventory and stock-location data.
GetLinnworksLocationIdByNameAsync
What it does: Looks up a Linnworks stock location by its name and returns that location's Linnworks location ID. Returns null if the name is empty or no location matches.
Signature: Task<string> GetLinnworksLocationIdByNameAsync(string locationName)
How to call it: await GetLinnworksLocationIdByNameAsync(locationName)
Parameter | Type | Required | Default | Description |
locationName |
| Yes | N/A | The name of the Linnworks stock location to look up, for example |
Returns: string. The matching Linnworks location ID, or null if no location matches.
Example: "Test Location" returns "8d384c87-5563-4dba-834c-d9ba4d21e3c2".
When to use it: In Product Inventory mappings when you need the Linnworks location ID that corresponds to a location name.
ConvertIPaaSLocationIdToLinnworksLocationNameAsync
What it does: Takes an iPaaS.com location ID and returns that location's name, which can then be used where Linnworks expects a location name.
Signature: Task<string> ConvertIPaaSLocationIdToLinnworksLocationNameAsync(object locationId)
How to call it: await ConvertIPaaSLocationIdToLinnworksLocationNameAsync(locationId)
Parameter | Type | Required | Default | Description |
locationId |
| Yes | N/A | The iPaaS.com location ID to convert, supplied as text. |
Returns: string. The location's name, or null if the iPaaS.com location cannot be found.
Example: "LOC123" returns "New York Warehouse".
When to use it: In Product Inventory mappings when you have an iPaaS.com location ID and need the corresponding location name.
ConvertIPaaSProductInventoryParentIdToSKUAsync
What it does: Takes an iPaaS.com product inventory parent ID and returns the corresponding product SKU.
Signature: Task<string> ConvertIPaaSProductInventoryParentIdToSKUAsync(object inventoryParentId)
How to call it: await ConvertIPaaSProductInventoryParentIdToSKUAsync(inventoryParentId)
Parameter | Type | Required | Default | Description |
inventoryParentId |
| Yes | N/A | The iPaaS.com inventory parent ID of the product, supplied as text. |
Returns: string. The product's SKU.
Example: "110090" returns "SAM980361460".
When to use it: In Product Inventory mappings when you need the SKU for an inventory record identified by its iPaaS.com parent ID.
ConvertIPaaSVariantInventoryParentIdToVariantSKUAsync
What it does: Takes an iPaaS.com product variant inventory parent ID and returns the corresponding variant SKU.
Signature: Task<string> ConvertIPaaSVariantInventoryParentIdToVariantSKUAsync(object variantInventoryParentId)
How to call it: await ConvertIPaaSVariantInventoryParentIdToVariantSKUAsync(variantInventoryParentId)
Parameter | Type | Required | Default | Description |
variantInventoryParentId |
| Yes | N/A | The iPaaS.com inventory parent ID of the product variant, supplied as text. |
Returns: string. The variant's SKU.
Example: "110090" returns "SAM980361460".
When to use it: In Product Variant Inventory mappings when you need the variant SKU for an inventory record identified by its iPaaS.com parent ID.
Orders and Shipping
Use these when mapping order shipment and tracking data to Linnworks.
GetPostalServiceIdByNameAsync
What it does: Looks up a Linnworks postal service by its name and returns that service's Linnworks postal service ID. Returns null if the name is empty or no service matches.
Signature: Task<string> GetPostalServiceIdByNameAsync(string postalServiceName)
How to call it: await GetPostalServiceIdByNameAsync(postalServiceName)
Parameter | Type | Required | Default | Description |
postalServiceName |
| Yes | N/A | The name of the Linnworks postal service to look up, for example |
Returns: string. The matching Linnworks postal service ID, or null if no service matches.
Example: "DHL Express" returns "f6ee9abf-2cc0-47e4-bcbe-93c90cdeb28fd".
When to use it: When writing shipment or tracking information to a Linnworks order and you need the Linnworks postal service ID that corresponds to a service name in your source data.