This document outlines the purpose, technology, use cases, methods, objects and examples for using the Gift Registry API.
This document focuses on the SOAP interface to this API.
The Gift Registry API provides programmatic access to the gift registry database and allows for retrieval and management of customer gift registry data within the system.
The Gift Registry API exposes two primary native interfaces via .NET and SOAP.
Full documentation for this interface is available in the API Reference.
This section documents the SOAP interface to the API.
The SOAP API endpoint for any site is located at https://[siteurl]/global/api/giftregistry.asmx
This endpoint is enabled for access via SOAP as well as HTTP GET and POST. The Service Description is also available directly via this endpoint.
Note: For systems with satellite sites, the API will be available only under the primary site URL.
The Gift Registry API via SOAP uses the Permissions System to allow and deny access to users. Use of the API requires a user to be granted the various actions (under iSAMS/API/GiftRegistry) to be able to authenticate and perform the various actions available under this API.
Error handling is primarily left to the caller. Any methods that return an ApiResponse object will provide additional details that can be used to assist when debugging problems.
Where a "Call Identifier" is returned in the Message field of the ApiResponse, then more information can be obtained by contacting eStar.
Available methods are listed below.
Available objects are listed below.
Gift Registry API usage examples are available. These examples demonstrate the use of the API via a SOAP interface and are available in C#.
See Authenticate.
Searches the gift registry database, returning the gift registry IDs of all gift registries matching the specified search term(s).
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this call. |
| name | String | All or part of the registrant's or co-registrant's name (i.e. first and last names, separated by a space) to search for. |
| String | All or part of the registrant's or co-registrant's email address to search for. | |
| externalIdentifier | String | All or part of the gift registry's external identifier to search for. |
| eventDate | Nullable<DateTime> | Date of the gift registry's occasion. |
Returns an IntegerArrayApiResponse containing the Gift Registry IDs of all gift registries matching the supplied search terms.
This method will return the Gift Registry IDs of all gift registries with details matching the input search terms. Results are based on all or part of the individual search terms matching the appropriate gift registry data.
Where more than one search term is provided, the results will be filtered on all provided search terms.
The name search term will return results based on both the registrant's and the co-registrant's first and last names, combined and separated by a space. Searching for a single first or last name is also supported.
eventDate will filter on the day component of eventDate, and ignores the time component of the supplied eventDate.
Empty, null, or all-whitespace search terms are ignored when filtering results.
Retrieves a gift registry using the supplied gift registry ID.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this call. |
| registryID | Integer | Gift registry ID of the gift registry to retrieve. |
Returns a GiftRegistryApiResponse containing a Registry object for the supplied gift registry ID as the sole entry in the GiftRegistryApiResponse.Data array.
Retrieves a set of gift registries using the supplied gift registry IDs.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this call. |
| registryIDs | Integer[] | Gift registry IDs of the gift registries to retrieve. |
Returns a GiftRegistryApiResponse containing an array of Registry objects for the supplied gift registry IDs in the GiftRegistryApiResponse.Data field.
Records sales against a set of gift registry items on a gift registry.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this call. |
| registryID | Integer | Gift registry ID of the gift registry to record sales against. |
| sales | RegistrySale[] | The sales to record against items in the specified gift registry. |
Returns an ApiResponse indicating success or failure.
The sales will be recorded against the user associated with the authentication token. Use RegistrySale.Comment if more detail is required.
Records refunds against a set of gift registry items on a gift registry.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this call. |
| registryID | Integer | Gift registry ID of the gift registry to record refunds against. |
| refunds | RegistryRefund[] | The refunds to record against items in the specified gift registry. |
Returns an ApiResponse indicating success or failure.
The refunds will be recorded against the user associated with the authentication token. Use RegistryRefund.Comment if more detail is required.
All dates and times are in UTC.
See ApiResponse.
Contains basic information about the result of a method call, along with an array of Registry objects.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| Success | Boolean | Indicates the success or failure of an API method call. | A failure (false) response should contain a failure Code and Message in the respective fields. |
| Code | Integer | A response code for the method call. | |
| Message | String | Message or output from the method call. | |
| Data | Registry[] | Array of Registry objects returned from the method call. | May not be populated if Success is true (for example, if a search returned no results). Will not be populated if Success if false. |
A Registry contains information about a customer's gift registry.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| ID | Integer | The unique gift registry ID. | |
| ExternalIdentifier | String | The external identifier of the registry. | This field can be used to identify a gift registry in a system external to . |
| Active | Boolean | Whether the gift registry is active or not. | |
| Website | Integer | The website ID of the website the gift registry is associated with. | |
| DateCreated | DateTime | When the gift registry was created in the system. | |
| CustomerID | Integer | The registrant's customer ID. | More detail about the registrant can be retrieved through the Customer API. |
| CustomerForeignIdentity | String | Foreign identity of the registrant. | The foreign identity is a unique identifier for a customer in a system external to . |
| FirstName | String | The registrant's first name. | |
| LastName | String | The registrant's last name. | |
| String | The registrant's email address. | ||
| Phone | String | The registrant's phone number. | |
| Occasion | String | The type of occasion the registry is for. | Available occasions can be managed through the Gift Registry administration console. Typical occasions include birthdays and weddings. |
| EventDate | Nullable<DateTime> | The date the registry event occurs. | May be null if the event date hasn't been set. |
| DeliveryDate | Nullable<DateTime> | The registrant's preferred delivery date for purchased registry items. | May be null if the delivery date hasn't been set. |
| Title | String | The title of the registry. | |
| Detail | String | Additional details on the registry's event. | |
| InvitationInserts | Nullable<Integer> | The requested number of invitation inserts. | Zero or null if InvitationInserts has not been set. |
| ExchangeCards | Boolean | Whether the registrant would like exchange cards for purchased items or not. | |
| Store | String | The name of the store the gift registry is managed through. | Stores can be managed through the Gift Registry administration console. |
| CoRegistrant | CoRegistrant | The co-registrant's details. | |
| Address | RegistryAddress | The gift registry delivery address. | |
| RegistryItems | RegistryItem[] | The items on the gift registry. | |
| Attributes | NameValuePair[] | Additional information attached to the gift registry. | These attributes are arbitrary key-value data pairs stored against a gift registry, and may differ between systems. |
The registrant is a customer in the system. Registrant details can be retrieved and updated using the Customer API.
A co-registrant is another person associated with a gift registry. For example, a wedding gift registry may record the bride as the registrant and the groom as the co-registrant.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| FirstName | String | The co-registrant's first name. | |
| LastName | String | The co-registrant's last name. | |
| String | The co-registrant's email address. |
A co-registrant is not a customer in the system, and does not have a customer ID or foreign identity. All data held by the system on a co-registrant is represented above.
A field will be empty if the system doesn't hold that data for the co-registrant.
A RegistryAddress is the delivery address for a gift registry.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| Company | String | The company to deliver to. | |
| StreetAddress | String | The street part of the delivery address. | |
| StreetAddress2 | String | An additional address line for the street part of the delivery address. | |
| Suburb | String | The suburb part of the delivery address. | |
| City | String | The city part of the delivery address. | |
| State | String | The state part of the delivery address. | |
| Postcode | String | The postcode part of the delivery address. | |
| Country | String | The country part of the delivery address. | Country is stored as an ISO three-letter country code. |
| ContactPhoneNumber | String | The phone number associated with the delivery address. |
Fields may be empty depending on what data the site requires for a registry delivery address.
A product item requested by the registrant on their gift registry.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| ID | Integer | Unique identifier for the registry item. | This is a gift registry item ID, not a product item ID. |
| Barcode | String | The barcode of the registry item. | |
| Title | String | The title of the registry item. | |
| Colour | String | The colour of the registry item. | |
| Size | String | The size of the registry item. | |
| Price | Decimal | The unit net price of the registry item. | |
| Requested | Integer | The quantity of the registry item that has been requested by the registrant for a gift registry. | |
| Purchased | Integer | The quantity of the registry item that has been purchased for a gift registry. | |
| Locked | Integer | The quantity of the registry item that has been purchased for a gift registry but has not dispatched and is still in progress. |
Gift registry items are stored independently to product items. The Barcode identifies the corresponding product item.
A RegistrySale is used to record the sale of an item against a gift registry.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| ID | Integer | The ID of the gift registry item to record the sale against. | Obtained by retrieving a Registry. |
| Quantity | Integer | The quantity of the gift registry item purchased in the sale. | |
| UnitNet | Decimal | The unit net price of the gift registry item purchased in the sale. | |
| Reference | String | A transaction reference for this sale. | |
| Comment | String | Free-text field. Can be used to store additional information against the sale. |
A RegistryRefund is used to record the refund of an item against a gift registry.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| ID | Integer | The ID of the gift registry item to record the refund against. | Obtained by retrieving a Registry. |
| Quantity | Integer | The quantity of the gift registry item being returned in the refund. | |
| UnitNet | Decimal | The unit net price of the gift registry item being returned in the refund. | |
| Reference | String | A transaction reference for this refund. | |
| Comment | String | Free-text field. Can be used to store additional information against the refund. |
See NameValuePair.
The Gift Registry API returns standard API response codes.