Overview
The ShipBob integration provides a set of ready-made functions you can call when building mappings. They handle common lookups and conversions for ShipBob, such as reading customer details from iPaaS.com, resolving a ShipBob product by reference ID or name, validating or defaulting a shipping method, and converting a location group into iPaaS.com location IDs, so you don't have to write that logic yourself.
Where you can use these functions
These functions are available anywhere you write a formula for the ShipBob 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 GetShipBobProductIdByName(channelId, name).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 function that returns a
Taskis asynchronous and must be called withawait, as shown in each How to call it example.Optional parameters are marked in the parameter table, along with the value used when you omit them.
Each function runs at sync time, against the data in your connected ShipBob account and your iPaaS.com subscription.
The functions are grouped below by the area of the integration they support.
Customers
Use these to read customer details from iPaaS.com when mapping a ShipBob transaction.
GetiPaaSCustomerData
What it does: Reads a single named field from an iPaaS.com customer record, looked up by customer ID or email address. Field names are matched loosely, ignoring case and punctuation. Returns nothing if the customer or field is not found.
Signature: Task<object> GetiPaaSCustomerData(object customerId, string requiredField)
How to call it: await GetiPaaSCustomerData(customerId, requiredField)
Parameter | Type | Required | Default | Description |
customerId |
| Yes | N/A | The iPaaS.com customer ID, or the customer email address (a value containing |
requiredField |
| Yes | N/A | The name of the customer field to return (for example |
Returns: object. The requested field's value, or nothing if the customer or field is not found.
Example: await GetiPaaSCustomerData("123456", "Name") returns the customer's full name.
When to use it: When mapping a value out of an iPaaS.com customer record and you have the customer ID or email.
GetiPaaSCustomerName
What it does: Returns the full name of an iPaaS.com customer, looked up by customer ID or email address. If the customer has no name, the part of the email before the @ is used. Returns nothing if the customer is not found.
Signature: Task<object> GetiPaaSCustomerName(object customerId)
How to call it: await GetiPaaSCustomerName(customerId)
Parameter | Type | Required | Default | Description |
customerId |
| Yes | N/A | The iPaaS.com customer ID, or the customer email address (a value containing |
Returns: object. The customer's full name (first and last name), or the email name if no name is set, or nothing if the customer is not found.
Example: await GetiPaaSCustomerName("12345") returns the customer's full name.
When to use it: When mapping a recipient name to ShipBob from an iPaaS.com customer, typically on a transaction.
GetiPaaSCustomerEmail
What it does: Returns the email address of an iPaaS.com customer, looked up by customer ID or email address. Returns nothing if the customer is not found.
Signature: Task<object> GetiPaaSCustomerEmail(object customerId)
How to call it: await GetiPaaSCustomerEmail(customerId)
Parameter | Type | Required | Default | Description |
customerId |
| Yes | N/A | The iPaaS.com customer ID, or the customer email address (a value containing |
Returns: object. The customer's email address, or nothing if the customer is not found.
Example: await GetiPaaSCustomerEmail("12345") returns the customer's email address.
When to use it: When mapping a recipient email to ShipBob from an iPaaS.com customer, typically on a transaction.
GetiPaaSCustomerPhoneNumber
What it does: Returns the customer number stored on an iPaaS.com customer record, looked up by customer ID or email address. The iPaaS.com customer record does not carry a separate phone number, so this returns the customer number. Returns nothing if the customer is not found.
Signature: Task<object> GetiPaaSCustomerPhoneNumber(object customerId)
How to call it: await GetiPaaSCustomerPhoneNumber(customerId)
Parameter | Type | Required | Default | Description |
customerId |
| Yes | N/A | The iPaaS.com customer ID, or the customer email address (a value containing |
Returns: object. The iPaaS.com customer number, or nothing if the customer is not found.
Example: await GetiPaaSCustomerPhoneNumber("12345") returns the customer number for that customer.
When to use it: When mapping the iPaaS.com customer number for a customer looked up by ID or email. To map a recipient's phone number, use GetMatchedPhoneNumberinTransactionAddress, which reads the phone number from the transaction address.
GetMatchedPhoneNumberinTransactionAddress
What it does: Returns the phone number from an iPaaS.com transaction's address, choosing the primary shipping or a non-primary shipping address. Returns nothing if the address or phone number is not found.
Signature: Task<string> GetMatchedPhoneNumberinTransactionAddress(object iPaaSAddress, bool IsPrimaryShipping = true)
How to call it: await GetMatchedPhoneNumberinTransactionAddress(iPaaSAddress)
Parameter | Type | Required | Default | Description |
iPaaSAddress |
| Yes | N/A | The iPaaS.com transaction address to read the phone number from. |
IsPrimaryShipping |
| No |
| When |
Returns: string. The matching address phone number, or nothing if it is not found.
Example: await GetMatchedPhoneNumberinTransactionAddress(iPaaSAddress, true) returns the phone number from the primary shipping address.
When to use it: When mapping a recipient phone number to ShipBob from an iPaaS.com transaction address.
Products
Use these to resolve a ShipBob product or its name when mapping transaction lines and inventory.
GetShipBobProductIdByReferenceId
What it does: Looks up a ShipBob product by reference ID (for example a SKU) within a channel and returns its ShipBob product ID. An exact variant-SKU match is preferred over a looser match. Returns nothing if no product matches.
Signature: Task<string?> GetShipBobProductIdByReferenceId(string channelId, string referenceId)
How to call it: await GetShipBobProductIdByReferenceId(channelId, referenceId)
Parameter | Type | Required | Default | Description |
channelId |
| Yes | N/A | The ShipBob channel ID to search within. |
referenceId |
| Yes | N/A | The iPaaS.com product reference ID (for example the SKU) to search for. |
Returns: string?. The ShipBob product ID, or nothing if no product matches.
Example: await GetShipBobProductIdByReferenceId("73232", "SKU") returns the ShipBob product ID for the given reference.
When to use it: When mapping a transaction line or inventory record to ShipBob and you have the product reference ID.
GetShipBobProductIdByName
What it does: Looks up a ShipBob product by name within a channel and returns its ShipBob product ID. An exact name match is preferred over a looser match. Returns nothing if no product matches.
Signature: Task<string> GetShipBobProductIdByName(string channelId, string name)
How to call it: await GetShipBobProductIdByName(channelId, name)
Parameter | Type | Required | Default | Description |
channelId |
| Yes | N/A | The ShipBob channel ID to search within. |
name |
| Yes | N/A | The product name to search for in ShipBob. |
Returns: string. The ShipBob product ID, or nothing if no product matches.
Example: await GetShipBobProductIdByName("73232", "ProductName") returns the ShipBob product ID for the given name.
When to use it: When mapping a transaction line to ShipBob and you have the product name.
GetShipbobProductNameByRefrenceId
What it does: Looks up an iPaaS.com product by reference ID (for example a SKU) and returns its name. Returns an empty string if no product matches.
Signature: Task<string> GetShipbobProductNameByRefrenceId(string referenceId)
How to call it: await GetShipbobProductNameByRefrenceId(referenceId)
Parameter | Type | Required | Default | Description |
referenceId |
| Yes | N/A | The iPaaS.com product reference ID (for example the SKU) to look up. |
Returns: string. The product name, or an empty string if no product matches.
Example: await GetShipbobProductNameByRefrenceId("SKU") returns the name of the product with that reference ID.
When to use it: When mapping a transaction line to ShipBob and you need the product name from its reference ID.
Shipping Methods
Use these to default or validate a ShipBob shipping method when mapping an order.
GetDefaultShippingMethod
What it does: Returns the name of the default ShipBob shipping method, or the first available method if none is marked default. Raises an error if no shipping method is available.
Signature: Task<string> GetDefaultShippingMethod()
How to call it: await GetDefaultShippingMethod()
Parameters: none.
Returns: string. The name of the default (or first) ShipBob shipping method.
Example: await GetDefaultShippingMethod() returns the default ShipBob shipping method name.
When to use it: When mapping an order's shipping method to ShipBob and you want to fall back to the account's default.
ValidateShippingMethodByName
What it does: Checks that a shipping method name exists in ShipBob and returns it. The match is not case-sensitive. Raises an error if the name is not found.
Signature: Task<string> ValidateShippingMethodByName(string shippingMethodName)
How to call it: await ValidateShippingMethodByName(shippingMethodName)
Parameter | Type | Required | Default | Description |
shippingMethodName |
| Yes | N/A | The ShipBob shipping method name to validate. The match is not case-sensitive. |
Returns: string. The validated ShipBob shipping method name.
Example: await ValidateShippingMethodByName("DHL") returns "DHL" when it is a valid ShipBob shipping method.
When to use it: When mapping an order's shipping method to ShipBob and you want to confirm the name is valid before using it.
Locations
Use this to convert a ShipBob location group into iPaaS.com location IDs.
SetLocationIniPaaSGroupAsync
What it does: Converts a ShipBob location group into iPaaS.com location IDs, replacing each child location's ShipBob ID with its matching iPaaS.com location ID. If a location has no iPaaS.com match, a message naming that location is returned instead.
Signature: Task<object> SetLocationIniPaaSGroupAsync(object location)
How to call it: await SetLocationIniPaaSGroupAsync(location)
Parameter | Type | Required | Default | Description |
location |
| Yes | N/A | The ShipBob location group to convert, with its child locations. |
Returns: object. The list of child locations with their iPaaS.com location IDs, a message naming the first location that does not exist in iPaaS.com, or nothing if there are no matches.
Example: await SetLocationIniPaaSGroupAsync(location) returns the group's child locations with their iPaaS.com location IDs.
When to use it: When mapping a ShipBob location group into iPaaS.com and you need the iPaaS.com location IDs for its child locations.