csharp
java
javascript
php
python
ruby
typescript

gift_certificate

/gift_certificate

Create a gift certificate

Permissions:
  • gift_certificate_write

Produces: application/json
post
/gift_certificate/gift_certificates

Creates a gift certificate for this merchant account.

SDK Function Name: createGiftCertificate

Parameters
Parameter Description Location Data Type Required
gift_certificate_create_request Gift certificate create request body GiftCertificateCreateRequest required
Responses
Status Code Reason Response Model
200
 Successful response GiftCertificateResponse
400
 Bad Request 400
401
 Unauthorized 401
410
 Authorized Application Disabled 410
429
 Too Many Requests 429
500
 Server Side 500 
using System;
using com.ultracart.admin.v2.Api;
using com.ultracart.admin.v2.Model;

namespace SdkSample.gift_certificate
{
    // ReSharper disable once ClassNeverInstantiated.Global
    public class CreateGiftCertificate
    {

        public static void Execute()
        {
            var giftCertificate = CreateGiftCertificateCall();
            Utility.DumpObject(giftCertificate, "Gift Certificate");
        }

        // ReSharper disable once MemberCanBePrivate.Global
        public static GiftCertificate CreateGiftCertificateCall()
        {
            var api = new GiftCertificateApi(Constants.API_KEY);
            
            GiftCertificateCreateRequest createRequest = new GiftCertificateCreateRequest()
            {
                Amount = new Decimal(200.00),
                InitialLedgerDescription = "Created via C# SDK",
                MerchantNote = "Internal comment here",
                Email = "support@ultracart.com",
                ExpirationDts = DateTime.UtcNow.AddMonths(3).ToString("s", System.Globalization.CultureInfo.InvariantCulture)
            };

            // create does not take an expansion variable.  it will return the entire object by default.
            var gcResponse = api.CreateGiftCertificate(createRequest);
            return gcResponse.GiftCertificate;
        }
    }
}

package gift_certificate;

import com.ultracart.admin.v2.GiftCertificateApi;
import com.ultracart.admin.v2.models.GiftCertificate;
import com.ultracart.admin.v2.models.GiftCertificateCreateRequest;
import com.ultracart.admin.v2.models.GiftCertificateResponse;
import common.Constants;
import common.JSON;
import org.joda.time.DateTime;
import org.joda.time.format.DateTimeFormatter;
import org.joda.time.format.ISODateTimeFormat;

import java.math.BigDecimal;

public class CreateGiftCertificate {

  public static void main(String... args) throws Exception {

    // Don't use verifySsl=false in production.
    GiftCertificateApi giftCertificateApi = new GiftCertificateApi(Constants.API_KEY, Constants.VERIFY_SSL_FLAG, Constants.DEBUG_MODE);
    DateTimeFormatter fmt = ISODateTimeFormat.dateTimeNoMillis();

    GiftCertificateCreateRequest createRequest = new GiftCertificateCreateRequest();
    createRequest.setAmount(new BigDecimal("150.75"));
    createRequest.setInitialLedgerDescription("Issued instead of refund");
    createRequest.setMerchantNote("Created via Java SDK");
    createRequest.setEmail("perry@ultracart.com");
    createRequest.setExpirationDts(fmt.print(DateTime.now().plusMonths(3)));

    // create does not take an expansion variable.  it will return the entire object by default.
    GiftCertificateResponse gcResponse = giftCertificateApi.createGiftCertificate(createRequest);
    GiftCertificate giftCertificate = gcResponse.getGiftCertificate();

    System.out.println(JSON.toJSON(giftCertificate));

  }

}

var ucApi = require('ultra_cart_rest_api_v2');
const { apiClient } = require('../api.js');
var luxon = require('luxon');

var giftCertificateApi = new ucApi.GiftCertificateApi(apiClient);


let gcCreateRequest = new ucApi.GiftCertificateCreateRequest();
gcCreateRequest.amount = 150.75;
gcCreateRequest.initial_ledger_description = "Issued instead of refund";
gcCreateRequest.merchant_note = 'Problem Order: blah-12345\nIssued gift certificate due to stale product.\nIssued By: Customer Service Rep Joe Smith';
gcCreateRequest.email = 'support@ultracart.com';
gcCreateRequest.expiration_dts = luxon.DateTime.now().setZone('America/New_York').plus({months:3}).endOf('day').toISO();


// create does not take an expansion variable.  it will return the entire object by default.
giftCertificateApi.createGiftCertificate(gcCreateRequest, 
    function(error, data, response){
        let giftCertificate = data.gift_certificate;    
        console.log('giftCertificate', giftCertificate);
    });

<?php

use ultracart\v2\models\GiftCertificateCreateRequest;

require_once '../vendor/autoload.php';
require_once '../samples.php';

$gift_certificate_api = Samples::getGiftCertificateApi();

$expiration_dts = new DateTime('now');
$expiration_dts->modify('+3 month'); // or you can use '-90 day' for deduct


$gc_create_request = new GiftCertificateCreateRequest();
$gc_create_request->setAmount(150.75);
$gc_create_request->setInitialLedgerDescription("Issued instead of refund");
$gc_create_request->setMerchantNote('Problem Order: blah-12345\nIssued gift certificate due to stale product.\nIssued By: Customer Service Rep Joe Smith');
$gc_create_request->setEmail('support@ultracart.com');
$gc_create_request->setExpirationDts($expiration_dts->format('c'));
$gc_create_request->setMerchantNote("This is my merchant note.");


// create does not take an expansion variable.  it will return the entire object by default.
$api_response = $gift_certificate_api->createGiftCertificate($gc_create_request);

echo '<html lang="en"><body><pre>';
var_dump($api_response);
var_dump($api_response->getGiftCertificate());
echo '</pre></body></html>';




# create a gift certificate
from ultracart.apis import GiftCertificateApi
from ultracart.model.gift_certificate_create_request import GiftCertificateCreateRequest
from ultracart.rest import ApiException
from pprint import pprint
from samples import api_client
from datetime import datetime, timedelta

api_instance = GiftCertificateApi(api_client())

try:

    amount = 150.75
    expiration_dts = datetime.now() + timedelta(days=180)
    expiration_dts_iso8601 = expiration_dts.astimezone().isoformat('T', 'milliseconds')
    initial_ledger_description = "Issued instead of refund"
    merchant_note = 'Problem Order: blah-12345\nIssued gift certificate due to stale product.' \
                    '\nIssued By: Customer Service Rep Joe Smith'
    email = 'support@ultracart.com'
    gc_create_request = GiftCertificateCreateRequest(amount=amount,
                                                     email=email,
                                                     expiration_dts_iso8601=expiration_dts_iso8601,
                                                     initial_ledger_description=initial_ledger_description,
                                                     merchant_note=merchant_note)

    # create does not take an expansion variable.  it will return the entire object by default.
    gc_response = api_instance.create_gift_certificate(gc_create_request)
    gift_certificate = gc_response.gift_certificate

    pprint(gift_certificate)

except ApiException as e:
    print("Exception when calling GiftCertificateApi->create_gift_certificate: %s\n" % e)



require 'date'
require 'json'
require 'yaml'
require 'ultracart_api'
require_relative '../constants'

api = UltracartClient::GiftCertificateApi.new_using_api_key(Constants::API_KEY, Constants::VERIFY_SSL, Constants::DEBUG_MODE)

create_request = UltracartClient::GiftCertificateCreateRequest.new

expiration_dts = DateTime.now + 90
create_request.amount = 150.75
create_request.initial_ledger_description = "Issued instead of refund"
create_request.merchant_note = 'Problem Order: blah-12345\nIssued gift certificate due to stale product.\nIssued By: Customer Service Rep Joe Smith'
create_request.email = 'support@ultracart.com'
create_request.expiration_dts = expiration_dts.iso8601


# create does not take an expansion variable.  it will return the entire object by default.
api_response = api.create_gift_certificate(create_request)
gift_certificate = api_response.gift_certificate

puts gift_certificate.to_yaml


// I'm using the .js extension here so this file can be run stand-alone using node. Normally, there would be no extension.
import { giftCertificateApi } from '../api.js';
// import { giftCertificateApi } from '../api';

import { CreateGiftCertificateRequest, GiftCertificateCreateRequest } from 'ultracart_rest_api_v2_typescript';
import { DateTime } from 'luxon';


let gcCreateRequest: GiftCertificateCreateRequest = {};
gcCreateRequest.amount = 150.75;
gcCreateRequest.initial_ledger_description = "Issued instead of refund";
gcCreateRequest.merchant_note = 'Problem Order: blah-12345\nIssued gift certificate due to stale product.\nIssued By: Customer Service Rep Joe Smith';
gcCreateRequest.email = 'support@ultracart.com';
gcCreateRequest.expiration_dts = DateTime.now().setZone('America/New_York').plus({months:3}).endOf('day').toISO();

let createGiftCertificateRequest: CreateGiftCertificateRequest = {
    giftCertificateCreateRequest: gcCreateRequest
};


// create does not take an expansion variable.  it will return the entire object by default.
let gcResponse = await giftCertificateApi.createGiftCertificate(createGiftCertificateRequest);
let giftCertificate = gcResponse.gift_certificate;

console.log(giftCertificate);

Retrieve gift certificate by code

Permissions:
  • gift_certificate_read

Produces: application/json
post
/gift_certificate/gift_certificates/by_code/{code}

Retrieves a gift certificate from the account based on the code (the value the customer enters at checkout time).

SDK Function Name: getGiftCertificateByCode

Parameters
Parameter Description Location Data Type Required
code path string optional
Responses
Status Code Reason Response Model
200
 Successful response GiftCertificateResponse
400
 Bad Request 400
401
 Unauthorized 401
410
 Authorized Application Disabled 410
429
 Too Many Requests 429
500
 Server Side 500 
using com.ultracart.admin.v2.Api;
using com.ultracart.admin.v2.Model;

namespace SdkSample.gift_certificate
{
    // ReSharper disable once ClassNeverInstantiated.Global
    public class GetGiftCertificateByCode
    {
        // uncomment to run.  C# projects can only have one main.
        // public static void Main()
        // {
        //     var giftCertificate = GetGiftCertificateByCodeCall();
        //     Utility.DumpObject(giftCertificate, "Gift Certificate");
        // }

        // ReSharper disable once MemberCanBePrivate.Global
        public static GiftCertificate GetGiftCertificateByCodeCall()
        {
            var api = new GiftCertificateApi(Constants.API_KEY);
            
            const string code = "X8PV761V2Z";

            // by_code does not take an expansion variable.  it will return the entire object by default.
            var gcResponse = api.GetGiftCertificateByCode(code);
            return gcResponse.GiftCertificate;
        }
    }
}

package gift_certificate;

import com.ultracart.admin.v2.GiftCertificateApi;
import com.ultracart.admin.v2.models.GiftCertificate;
import com.ultracart.admin.v2.models.GiftCertificateResponse;
import common.Constants;
import common.JSON;

public class GetGiftCertificateByCode{

  public static void main(String ... args) throws Exception {

    GiftCertificateApi giftCertificateApi = new GiftCertificateApi(Constants.API_KEY, Constants.VERIFY_SSL_FLAG, Constants.DEBUG_MODE);

    String code = "93KHHXD6VH";

    // by_code does not take an expansion variable.  it will return the entire object by default.
    GiftCertificateResponse gcResponse = giftCertificateApi.getGiftCertificateByCode(code);
    GiftCertificate giftCertificate = gcResponse.getGiftCertificate();

    System.out.println(JSON.toJSON(giftCertificate));

  }

}

var ucApi = require('ultra_cart_rest_api_v2');
const { apiClient } = require('../api.js');

var giftCertificateApi = new ucApi.GiftCertificateApi(apiClient);

let code = 'NRQPHPCFVK';


// by_code does not take an expansion variable.  it will return the entire object by default.
giftCertificateApi.getGiftCertificateByCode(code, 
    function(error, data, response){
        let giftCertificate = data.gift_certificate;    
        console.log('giftCertificate', giftCertificate);
    });

<?php
require_once '../vendor/autoload.php';
require_once '../samples.php';

$gift_certificate_api = Samples::getGiftCertificateApi();
/** @noinspection SpellCheckingInspection */ $code = "93KHHXD6VH";

// by_code does not take an expansion variable.  it will return the entire object by default.
$api_response = $gift_certificate_api->getGiftCertificateByCode($code);


echo '<html lang="en"><body><pre>';
var_dump($api_response);
var_dump($api_response->getGiftCertificate());
echo '</pre></body></html>';




# get a gift certificate by code.

from ultracart.apis import GiftCertificateApi
from ultracart.rest import ApiException
from pprint import pprint
from samples import api_client

api_instance = GiftCertificateApi(api_client())

try:

    code = 'NRQPHPCFVK'

    # by_code does not take an expansion variable.  it will return the entire object by default.
    gc_response = api_instance.get_gift_certificate_by_code(code)
    gift_certificate = gc_response.gift_certificate

    pprint(gift_certificate)

except ApiException as e:
    print("Exception when calling GiftCertificateApi->get_gift_certificate_by_code: %s\n" % e)


# frozen_string_literal: true

require 'json'
require 'yaml'
require 'ultracart_api'
require_relative '../constants'

api = UltracartClient::GiftCertificateApi.new_using_api_key(Constants::API_KEY, Constants::VERIFY_SSL, Constants::DEBUG_MODE)

code = '74BX2Q8B7K'

# by_code does not take an expansion variable.  it will return the entire object by default.
api_response = api.get_gift_certificate_by_code(code)
gift_certificate = api_response.gift_certificate

puts gift_certificate.to_yaml


// I'm using the .js extension here so this file can be run stand-alone using node. Normally, there would be no extension.
import { giftCertificateApi } from '../api.js';
import { GetGiftCertificateByCodeRequest} from 'ultracart_rest_api_v2_typescript';


let code = 'NRQPHPCFVK'

// by_code does not take an expansion variable.  it will return the entire object by default.
const getGiftCertificateByCodeRequest: GetGiftCertificateByCodeRequest = { code: code};
let gcResponse = await giftCertificateApi.getGiftCertificateByCode(getGiftCertificateByCodeRequest);
let giftCertificate = gcResponse.gift_certificate;

console.log(giftCertificate);

Retrieve gift certificate by email

Permissions:
  • gift_certificate_read

Produces: application/json
post
/gift_certificate/gift_certificates/by_email/{email}

Retrieves all gift certificates from the account based on customer email.

SDK Function Name: getGiftCertificatesByEmail

Parameters
Parameter Description Location Data Type Required
email path string optional
Responses
Status Code Reason Response Model
200
 Successful response GiftCertificatesResponse
400
 Bad Request 400
401
 Unauthorized 401
410
 Authorized Application Disabled 410
429
 Too Many Requests 429
500
 Server Side 500 
using System.Collections.Generic;
using com.ultracart.admin.v2.Api;
using com.ultracart.admin.v2.Model;

namespace SdkSample.gift_certificate
{
    // ReSharper disable once ClassNeverInstantiated.Global
    public class GetGiftCertificatesByEmail
    {
        // uncomment to run.  C# projects can only have one main.
        // public static void Main()
        // {
        //     var giftCertificates = GetGiftCertificatesByEmailCall();
        //     Utility.DumpObject(giftCertificates, "Gift Certificates");
        //     foreach (var gc in giftCertificates)
        //     {
        //         Utility.DumpObject(gc, "Gift Certificate");
        //     }
        //     
        // }

        // ReSharper disable once MemberCanBePrivate.Global
        public static List<GiftCertificate> GetGiftCertificatesByEmailCall()
        {
            var api = new GiftCertificateApi(Constants.API_KEY);
            
            const string email = "support@ultracart.com";

            // by_email does not take an expansion variable.  it will return the entire object by default.
            var gcResponse = api.GetGiftCertificatesByEmail(email);
            return gcResponse.GiftCertificates;
        }
    }
}

package gift_certificate;

import com.ultracart.admin.v2.GiftCertificateApi;
import com.ultracart.admin.v2.models.GiftCertificate;
import com.ultracart.admin.v2.models.GiftCertificatesResponse;
import common.Constants;
import common.JSON;

import java.util.List;

public class GetGiftCertificatesByEmail {

  public static void main(String... args) throws Exception {

    GiftCertificateApi giftCertificateApi = new GiftCertificateApi(Constants.API_KEY, Constants.VERIFY_SSL_FLAG, Constants.DEBUG_MODE);

    String email = "support@ultracart.com";

    // by_email does not take an expansion variable.  it will return the entire object by default.
    GiftCertificatesResponse gcResponse = giftCertificateApi.getGiftCertificatesByEmail(email);
    List<GiftCertificate> giftCertificates = gcResponse.getGiftCertificates();

    for (GiftCertificate certificate : giftCertificates) {
      System.out.println(JSON.toJSON(certificate));
    }
  }
}

var ucApi = require('ultra_cart_rest_api_v2');
const { apiClient } = require('../api.js');

var giftCertificateApi = new ucApi.GiftCertificateApi(apiClient);

let email = 'support@ultracart.com';


// by_email does not take an expansion variable.  it will return the entire object by default.
giftCertificateApi.getGiftCertificatesByEmail(email, 
    function(error, data, response){
        let giftCertificates = data.gift_certificates;    
        console.log('giftCertificates', giftCertificates);
    });

<?php
require_once '../vendor/autoload.php';
require_once '../samples.php';

$gift_certificate_api = Samples::getGiftCertificateApi();

$email = "support@ultracart.com";

// by_email does not take an expansion variable.  it will return the entire object by default.
$api_response = $gift_certificate_api->getGiftCertificatesByEmail($email);


echo '<html lang="en"><body><pre>';
var_dump($api_response);
var_dump($api_response->getGiftCertificates());
echo '</pre></body></html>';




# get a gift certificate by gift_certificate_oid.

from ultracart.apis import GiftCertificateApi
from ultracart.rest import ApiException
from pprint import pprint
from samples import api_client

api_instance = GiftCertificateApi(api_client())

try:

    email = "support@ultracart.com"

    # by_email does not take an expansion variable.  it will return the entire object by default.
    gc_response = api_instance.get_gift_certificates_by_email(email)
    gift_certificates = gc_response.gift_certificates

    pprint(gift_certificates)

except ApiException as e:
    print("Exception when calling GiftCertificateApi->get_gift_certificates_by_email: %s\n" % e)


require 'json'
require 'yaml'
require 'ultracart_api'
require_relative '../constants'

api = UltracartClient::GiftCertificateApi.new_using_api_key(Constants::API_KEY, Constants::VERIFY_SSL, Constants::DEBUG_MODE)

email = 'support@ultracart.com'

# by_email does not take an expansion variable.  it will return the entire object by default.
api_response = api.get_gift_certificates_by_email(email)
gift_certificates = api_response.gift_certificates

puts gift_certificates.to_yaml

// I'm using the .js extension here so this file can be run stand-alone using node. Normally, there would be no extension.
import { giftCertificateApi } from '../api.js';
// import { giftCertificateApi } from '../api';


let email = 'support@ultracart.com';

// by_email does not take an expansion variable.  it will return the entire object by default.
let gcResponse = await giftCertificateApi.getGiftCertificatesByEmail({email: email});
let giftCertificates = gcResponse.gift_certificates;

console.log(giftCertificates);

Retrieve gift certificates by query

Permissions:
  • gift_certificate_read

Produces: application/json
post
/gift_certificate/gift_certificates/query

Retrieves gift certificates from the account. If no parameters are specified, all gift certificates will be returned. You will need to make multiple API calls in order to retrieve the entire result set since this API performs result set pagination.

SDK Function Name: getGiftCertificatesByQuery

Parameters
Parameter Description Location Data Type Required
gift_certificate_query Gift certificates query body GiftCertificateQuery required
_limit The maximum number of records to return on this one API call. (Max 200)
Default: 100 		query integer optional
_offset Pagination of the record set. Offset is a zero based index.
Default: 0 		query integer optional
_since Fetch customers that have been created/modified since this date/time. query dateTime optional
_sort The sort order of the customers. See Sorting documentation for examples of using multiple values and sorting by ascending and descending.
Allowed Values
  • customer_profile_id
  • billing.first_name
  • billing.last_name
  • billing.city
  • billing.state_region
  • billing.postal_code
  • billing.country_code
  • billing.day_phone
  • email
  • billing.evening_phone
  • last_modified_dts
  • last_modified_by
 query string optional
_expand The object expansion to perform on the result. See documentation for examples query string optional
Responses
Status Code Reason Response Model
200
 Successful response GiftCertificatesResponse
400
 Bad Request 400
401
 Unauthorized 401
410
 Authorized Application Disabled 410
429
 Too Many Requests 429
500
 Server Side 500 
using System.Collections.Generic;
using com.ultracart.admin.v2.Api;
using com.ultracart.admin.v2.Model;

namespace SdkSample.gift_certificate
{
    // ReSharper disable once ClassNeverInstantiated.Global
    public class GetGiftCertificateByQuery
    {
        // uncomment to run.  C# projects can only have one main.
        // public static void Main()
        // {
        //     var giftCertificates = GetGiftCertificateByQueryCall();
        //     foreach (var giftCertificate in giftCertificates)
        //     {
        //         Utility.DumpObject(giftCertificate, "Gift Certificate");    
        //     }
        // }


        private static List<GiftCertificate> GetGiftCertificateChunk(GiftCertificateApi api, int offset, int limit)
        {
            const string expansion = "ledger";

            // leaving query empty, so no filtering, and I should get all records returned.
            GiftCertificateQuery query = new GiftCertificateQuery();
            
            var gcResponse = api.GetGiftCertificatesByQuery(query, limit, offset, null, null, expansion);
                if(gcResponse.Success == true && gcResponse.GiftCertificates != null){
                    return gcResponse.GiftCertificates;
                }

                return new List<GiftCertificate>();
        }
        
        
        
        // ReSharper disable once MemberCanBePrivate.Global
        public static List<GiftCertificate> GetGiftCertificateByQueryCall()
        {
            var api = new GiftCertificateApi(Constants.API_KEY);

            List<GiftCertificate> giftCertificates = new List<GiftCertificate>();

            var iteration = 1;
            var offset = 0;
            var limit = 200;
            var moreRecordsToFetch = true;

            while( moreRecordsToFetch ){

                System.Console.WriteLine("executing iteration " + iteration);
                var chuckOfCertificates = GetGiftCertificateChunk(api, offset, limit);
                giftCertificates.AddRange(chuckOfCertificates);
                offset += limit;
                moreRecordsToFetch = chuckOfCertificates.Count == limit;
                iteration++;
                
            }
            

            return giftCertificates;
        }
    }
}

package gift_certificate;

import com.ultracart.admin.v2.GiftCertificateApi;
import com.ultracart.admin.v2.models.GiftCertificate;
import com.ultracart.admin.v2.models.GiftCertificateQuery;
import com.ultracart.admin.v2.models.GiftCertificatesResponse;
import com.ultracart.admin.v2.util.ApiException;
import common.Constants;
import common.JSON;

import java.util.ArrayList;
import java.util.List;

public class GetGiftCertificatesByQuery{

  public static List<GiftCertificate> getGiftCertificateChunk(GiftCertificateApi giftCertificateApi,
                                                                   int offset,
                                                                   int limit) throws ApiException {
    String expansion = "ledger";
    GiftCertificateQuery query = new GiftCertificateQuery();  // leave this empty to retrieve all records.
    GiftCertificatesResponse gcResponse = giftCertificateApi.getGiftCertificatesByQuery(query, limit, offset, null, null, expansion);
    if(gcResponse != null && gcResponse.getGiftCertificates() != null){
      return gcResponse.getGiftCertificates();
    }
    return new ArrayList<>();
  }

  public static void main(String ... args) throws Exception {

    GiftCertificateApi giftCertificateApi = new GiftCertificateApi(Constants.API_KEY, Constants.VERIFY_SSL_FLAG, Constants.DEBUG_MODE);

    ArrayList<GiftCertificate> giftCertificates = new ArrayList<>();
    int iteration = 1;
    int offset = 0;
    int limit = 200;
    boolean moreRecordsToFetch = true;

    while( moreRecordsToFetch ){

        System.out.println("executing iteration " + iteration);
        List<GiftCertificate> chuckOfCertificates = getGiftCertificateChunk(giftCertificateApi, offset, limit);
        giftCertificates.addAll(chuckOfCertificates);
        offset = offset + limit;
        moreRecordsToFetch = chuckOfCertificates.size() == limit;
        iteration++;

    }

    for (GiftCertificate giftCertificate : giftCertificates) {
      System.out.println(JSON.toJSON(giftCertificate));
    }
  }
}

var ucApi = require('ultra_cart_rest_api_v2');
const { apiClient } = require('../api.js');

var giftCertificateApi = new ucApi.GiftCertificateApi(apiClient);

var giftCertificates = [];
var offset = 0;
var limit = 200;

function finished(){
    console.log('giftCertificates', giftCertificates);
    console.log("count of certificates: ", giftCertificates.length);
}

function getGiftCertificateChunk(){
    let expansion = 'ledger';
    let query = new ucApi.GiftCertificateQuery(); // leaving this empty, so no filtering, and I should get all records returned.
    giftCertificateApi.getGiftCertificatesByQuery(query, { _limit: limit, _offset: offset, _expand: expansion }, function(error, data, response){
        if(data && data.gift_certificates){
            giftCertificates = giftCertificates.concat(data.gift_certificates);

            offset = offset + limit;
            if(data.gift_certificates.length == limit){
                getGiftCertificateChunk();
            } else {
                finished();
            }
        } else {
            finished();
        }
    });
}

getGiftCertificateChunk();


<?php

use ultracart\v2\api\GiftCertificateApi;
use ultracart\v2\models\GiftCertificateQuery;

require_once '../vendor/autoload.php';
require_once '../samples.php';

$gift_certificate_api = Samples::getGiftCertificateApi();


function getGiftCertificateChunk(GiftCertificateApi $gift_certificate_api, int $offset, int $limit): array
{
    $expansion = "ledger";
    $query = new GiftCertificateQuery();  // leave this empty to retrieve all records.
    $api_response = $gift_certificate_api->getGiftCertificatesByQuery($query, $limit, $offset, null, null, $expansion);
    if($api_response->getGiftCertificates() != null){
        return $api_response->getGiftCertificates();
    }
    return [];
}

$gift_certificates = [];

$iteration = 1;
$offset = 0;
$limit = 200;
$more_records_to_fetch = true;

while( $more_records_to_fetch ){

    echo "executing iteration " . $iteration . '<br>';
    $chunk_of_certificates = getGiftCertificateChunk($gift_certificate_api, $offset, $limit);
    $gift_certificates = array_merge($gift_certificates, $chunk_of_certificates);
    $offset = $offset + $limit;
    $more_records_to_fetch = count($chunk_of_certificates) == $limit;
    $iteration++;

}

echo '<html lang="en"><body><pre>';
var_dump($gift_certificates);
echo '</pre></body></html>';



# retrieve all items using chunking if necessary

from ultracart.apis import GiftCertificateApi
from ultracart.model.gift_certificate_query import GiftCertificateQuery
from ultracart.rest import ApiException
from samples import api_client
import time

api_instance = GiftCertificateApi(api_client())

expand = 'ledger'


def get_gift_certificates_chunk(_offset=0, _limit=200):
    gc_query = GiftCertificateQuery()
    gc_response = api_instance.get_gift_certificates_by_query(gc_query, offset=_offset, limit=_limit, expand=expand)
    if gc_response.success:
        return gc_response.gift_certificates
    # if unsuccessful, return empty array
    return []


gift_certificates = []
try:

    iteration = 1
    offset = 0
    limit = 200
    need_more_records = True

    while need_more_records:
        print("executing iteration " + str(iteration))
        block_of_certs = get_gift_certificates_chunk(offset, limit)
        gift_certificates.extend(block_of_certs)
        offset = offset + limit
        need_more_records = len(block_of_certs) == limit
        iteration = iteration + 1
        time.sleep(3)  # pace your calls or the rate limiter was slam down on your script.

    # pprint(gift_certificates)
    rec_num = 1
    for gc in gift_certificates:
        print(rec_num, ") oid: ", gc.gift_certificate_oid, ", code: ", gc.code)
        rec_num = rec_num + 1

except ApiException as e:
    print("Exception when calling GiftCertificateApi->get_gift_certificates_by_query: %s\n" % e)


require 'json'
require 'yaml'
require 'ultracart_api'
require_relative '../constants'

api = UltracartClient::GiftCertificateApi.new_using_api_key(Constants::API_KEY, Constants::VERIFY_SSL, Constants::DEBUG_MODE)

def get_gift_certificates_chuck(api, offset, limit)
  expansion = 'ledger'.freeze
  query = UltracartClient::GiftCertificateQuery.new # leaving this empty, so no filtering, and I should get all records returned.
  api_response = api.get_gift_certificates_by_query(query, { _limit: limit, _offset: offset, _expand: expansion })
  return api_response.gift_certificates unless api_response.gift_certificates.nil?

  []
end


gift_certificates = []

iteration = 1
offset = 0
limit = 200
more_records_to_fetch = true

while more_records_to_fetch

  puts "executing iteration #{iteration}"
  chuck_of_certificates = get_gift_certificates_chuck(api, offset, limit)
  gift_certificates.push(*chuck_of_certificates)
  offset += limit
  more_records_to_fetch = chuck_of_certificates.length == limit
  iteration += 1

end

puts gift_certificates.to_yaml


// I'm using the .js extension here so this file can be run stand-alone using node. Normally, there would be no extension.
import { giftCertificateApi } from '../api.js';
// import { giftCertificateApi } from '../api';

import { GiftCertificate, GiftCertificateQuery } from 'ultracart_rest_api_v2_typescript';

let expansion = 'ledger';

async function getGiftCertificateChunk(offset: number = 0, limit: number = 200): Promise<GiftCertificate[]>{
    let query: GiftCertificateQuery = {}; // leaving this empty, so no filtering, and I should get all records returned.
    let gcResponse = await giftCertificateApi.getGiftCertificatesByQuery({giftCertificateQuery: query, limit: limit, offset: offset, expand: expansion});
    if(gcResponse.success && gcResponse.gift_certificates !== undefined){
        return gcResponse.gift_certificates;
    }
    return [];
}

let giftCertificates: GiftCertificate[] = [];

let iteration = 1;
let offset = 0;
let limit = 200;
let moreRecordsToFetch = true;

while( moreRecordsToFetch ){

    console.log("executing iteration " + iteration);
    let chuckOfCertificates = await getGiftCertificateChunk(offset, limit);
    giftCertificates = giftCertificates.concat(chuckOfCertificates);
    offset = offset + limit
    moreRecordsToFetch = chuckOfCertificates.length === limit;
    iteration = iteration + 1

}

// console.log(giftCertificates);
giftCertificates.forEach(gc => {
    console.log('oid: ' + gc.gift_certificate_oid + ", code: " + gc.code);
});

Delete a gift certificate

Permissions:
  • gift_certificate_write

Produces: application/json
delete
/gift_certificate/gift_certificates/{gift_certificate_oid}

Deletes a gift certificate for this merchant account.

SDK Function Name: deleteGiftCertificate

Parameters
Parameter Description Location Data Type Required
gift_certificate_oid path integer (int32) optional
Responses
Status Code Reason Response Model
400
 Bad Request 400
401
 Unauthorized 401
410
 Authorized Application Disabled 410
429
 Too Many Requests 429
500
 Server Side 500 
using com.ultracart.admin.v2.Api;
using com.ultracart.admin.v2.Model;

namespace SdkSample.gift_certificate
{
    // ReSharper disable once ClassNeverInstantiated.Global
    public class DeleteGiftCertificate
    {
        // uncomment to run.  C# projects can only have one main.
        // public static void Main()
        // {
        //     var giftCertificate = DeleteGiftCertificateCall();
        //     Utility.DumpObject(giftCertificate, "Gift Certificate");
        // }

        // ReSharper disable once MemberCanBePrivate.Global
        public static GiftCertificate DeleteGiftCertificateCall()
        {
            var api = new GiftCertificateApi(Constants.API_KEY);
            
            const int giftCertificateOid = 676713;
            api.DeleteGiftCertificate(giftCertificateOid);

            // if I re-query the gift certificate after deleting, I will still get an object back, but the
            // deleted flag on the object will be true.
            // by_oid does not take an expansion variable.  it will return the entire object by default.
            var gcResponse = api.GetGiftCertificateByOid(giftCertificateOid);
            return gcResponse.GiftCertificate;
        }
    }
}

package gift_certificate;

import com.ultracart.admin.v2.GiftCertificateApi;
import com.ultracart.admin.v2.models.GiftCertificate;
import com.ultracart.admin.v2.models.GiftCertificateResponse;
import common.Constants;
import common.JSON;

public class DeleteGiftCertificate{

  public static void main(String ... args) throws Exception {

    GiftCertificateApi giftCertificateApi = new GiftCertificateApi(Constants.API_KEY, Constants.VERIFY_SSL_FLAG, Constants.DEBUG_MODE);

    int giftCertificateOid = 676713;

    giftCertificateApi.deleteGiftCertificate(giftCertificateOid);

    // if I query the gift certificate again, I will get an object back, but the deleted property will be true.
    // by_oid does not take an expansion variable.  it will return the entire object by default.
    GiftCertificateResponse gcResponse = giftCertificateApi.getGiftCertificateByOid(giftCertificateOid);
    GiftCertificate giftCertificate = gcResponse.getGiftCertificate();

    System.out.println(JSON.toJSON(giftCertificate));

  }

}

var ucApi = require('ultra_cart_rest_api_v2');
const { apiClient } = require('../api.js');

var giftCertificateApi = new ucApi.GiftCertificateApi(apiClient);

let giftCertificateOid = 676713;

giftCertificateApi.deleteGiftCertificate(giftCertificateOid, function(error, data, response){

    // requery the gift certificate and an object is still returned, even after deleting.
    // However, the object's deleted property will now be true.
    // by_oid does not take an expansion variable.  it will return the entire object by default.
    giftCertificateApi.getGiftCertificateByOid(giftCertificateOid, 
        function(error, data, response){
            let giftCertificate = data.gift_certificate;    
            console.log('giftCertificate', giftCertificate);
        });

});




<?php
require_once '../vendor/autoload.php';
require_once '../samples.php';

$gift_certificate_api = Samples::getGiftCertificateApi();

$gift_certificate_oid = 676713;

// by_oid does not take an expansion variable.  it will return the entire object by default.
$api_response = $gift_certificate_api->deleteGiftCertificate($gift_certificate_oid);


// if we re-query the gift certificate, an object will still return.  however, the deleted property will be true
// by_oid does not take an expansion variable.  it will return the entire object by default.
$api_response = $gift_certificate_api->getGiftCertificateByOid($gift_certificate_oid);


echo '<html lang="en"><body><pre>';
var_dump($api_response);
var_dump($api_response->getGiftCertificate());
echo '</pre></body></html>';




# delete a gift certificate

from ultracart.apis import GiftCertificateApi
from ultracart.rest import ApiException
from pprint import pprint
from samples import api_client

api_instance = GiftCertificateApi(api_client())

try:

    gift_certificate_oid = 676777

    # by_code does not take an expansion variable.  it will return the entire object by default.
    api_instance.delete_gift_certificate(gift_certificate_oid)

    # if I query the gift certificate now, it will still return to me, but the deleted property will be True
    gc_response = api_instance.get_gift_certificate_by_oid(gift_certificate_oid)
    gift_certificate = gc_response.gift_certificate

    pprint(gift_certificate)

except ApiException as e:
    print("Exception when calling GiftCertificateApi->delete_gift_certificate: %s\n" % e)


require 'json'
require 'yaml'
require 'ultracart_api'
require_relative '../constants'

api = UltracartClient::GiftCertificateApi.new_using_api_key(Constants::API_KEY, Constants::VERIFY_SSL, Constants::DEBUG_MODE)

gift_certificate_oid = 676_713


api.delete_gift_certificate(gift_certificate_oid)

# re-querying the gift certificate will still return an object, but the deleted property will be true.
# by_oid does not take an expansion variable.  it will return the entire object by default.
api_response = api.get_gift_certificate_by_oid(gift_certificate_oid)
gift_certificate = api_response.gift_certificate

puts gift_certificate.to_yaml


// I'm using the .js extension here so this file can be run stand-alone using node. Normally, there would be no extension.
import { DeleteGiftCertificateRequest, GetGiftCertificateByOidRequest } from 'ultracart_rest_api_v2_typescript';
import { giftCertificateApi } from '../api.js';
// import { giftCertificateApi } from '../api';


let giftCertificateOid = 676713;


const deleteGiftCertificateRequest: DeleteGiftCertificateRequest = {
    giftCertificateOid: giftCertificateOid
}
await giftCertificateApi.deleteGiftCertificate(deleteGiftCertificateRequest);

// if I query the gift certificate now, it will still return as a valid object, but the deleted flag will be true.
const getGiftCertificateByOidRequest: GetGiftCertificateByOidRequest = {
    giftCertificateOid: giftCertificateOid
};
let gcResponse = await giftCertificateApi.getGiftCertificateByOid(getGiftCertificateByOidRequest);
let giftCertificate = gcResponse.gift_certificate;

console.log(giftCertificate);

Retrieve gift certificate by oid

Permissions:
  • gift_certificate_read

Produces: application/json
post
/gift_certificate/gift_certificates/{gift_certificate_oid}

Retrieves a gift certificate from the account based on the internal primary key.

SDK Function Name: getGiftCertificateByOid

Parameters
Parameter Description Location Data Type Required
gift_certificate_oid path integer (int32) optional
Responses
Status Code Reason Response Model
200
 Successful response GiftCertificateResponse
400
 Bad Request 400
401
 Unauthorized 401
410
 Authorized Application Disabled 410
429
 Too Many Requests 429
500
 Server Side 500 
using com.ultracart.admin.v2.Api;
using com.ultracart.admin.v2.Model;

namespace SdkSample.gift_certificate
{
    // ReSharper disable once ClassNeverInstantiated.Global
    public class GetGiftCertificateByOid
    {
        // uncomment to run.  C# projects can only have one main.
        // public static void Main()
        // {
        //     var giftCertificate = GetGiftCertificateByOidCall();
        //     Utility.DumpObject(giftCertificate, "Gift Certificate");
        // }

        // ReSharper disable once MemberCanBePrivate.Global
        public static GiftCertificate GetGiftCertificateByOidCall()
        {
            var api = new GiftCertificateApi(Constants.API_KEY);
            
            const int giftCertificateOid = 676713;

            // by_oid does not take an expansion variable.  it will return the entire object by default.
            var gcResponse = api.GetGiftCertificateByOid(giftCertificateOid);
            return gcResponse.GiftCertificate;
        }
    }
}

package gift_certificate;

import com.ultracart.admin.v2.GiftCertificateApi;
import com.ultracart.admin.v2.models.GiftCertificate;
import com.ultracart.admin.v2.models.GiftCertificateResponse;
import common.Constants;
import common.JSON;

public class GetGiftCertificateByOid{

  public static void main(String ... args) throws Exception {

    GiftCertificateApi giftCertificateApi = new GiftCertificateApi(Constants.API_KEY, Constants.VERIFY_SSL_FLAG, Constants.DEBUG_MODE);

    int giftCertificateOid = 676713;

    // by_oid does not take an expansion variable.  it will return the entire object by default.
    GiftCertificateResponse gcResponse = giftCertificateApi.getGiftCertificateByOid(giftCertificateOid);
    GiftCertificate giftCertificate = gcResponse.getGiftCertificate();

    System.out.println(JSON.toJSON(giftCertificate));

  }

}

var ucApi = require('ultra_cart_rest_api_v2');
const { apiClient } = require('../api.js');

var giftCertificateApi = new ucApi.GiftCertificateApi(apiClient);

let giftCertificateOid = 676713;


// by_oid does not take an expansion variable.  it will return the entire object by default.
giftCertificateApi.getGiftCertificateByOid(giftCertificateOid, 
    function(error, data, response){
        let giftCertificate = data.gift_certificate;    
        console.log('giftCertificate', giftCertificate);
    });

<?php
require_once '../vendor/autoload.php';
require_once '../samples.php';

$gift_certificate_api = Samples::getGiftCertificateApi();

$gift_certificate_oid = 676713;

// by_oid does not take an expansion variable.  it will return the entire object by default.
$api_response = $gift_certificate_api->getGiftCertificateByOid($gift_certificate_oid);


echo '<html lang="en"><body><pre>';
var_dump($api_response);
var_dump($api_response->getGiftCertificate());
echo '</pre></body></html>';




# get a gift certificate by gift_certificate_oid.

from ultracart.apis import GiftCertificateApi
from ultracart.rest import ApiException
from pprint import pprint
from samples import api_client


api_instance = GiftCertificateApi(api_client())

try:

    gift_certificate_oid = 676713

    # by_oid does not take an expansion variable.  it will return the entire object by default.
    gc_response = api_instance.get_gift_certificate_by_oid(gift_certificate_oid)
    gift_certificate = gc_response.gift_certificate

    pprint(gift_certificate)

except ApiException as e:
    print("Exception when calling GiftCertificateApi->get_gift_certificate_by_oid: %s\n" % e)


require 'json'
require 'yaml'
require 'ultracart_api'
require_relative '../constants'

api = UltracartClient::GiftCertificateApi.new_using_api_key(Constants::API_KEY, Constants::VERIFY_SSL, Constants::DEBUG_MODE)

gift_certificate_oid = 676_713

# by_oid does not take an expansion variable.  it will return the entire object by default.
api_response = api.get_gift_certificate_by_oid(gift_certificate_oid)
gift_certificate = api_response.gift_certificate

puts gift_certificate.to_yaml


// I'm using the .js extension here so this file can be run stand-alone using node. Normally, there would be no extension.
import { giftCertificateApi } from '../api.js';
// import { giftCertificateApi } from '../api';


let giftCertificateOid = 676713;

// by_oid does not take an expansion variable.  it will return the entire object by default.
let gcResponse = await giftCertificateApi.getGiftCertificateByOid({giftCertificateOid: giftCertificateOid});
let giftCertificate = gcResponse.gift_certificate;

console.log(giftCertificate);

Update a gift certificate

Permissions:
  • gift_certificate_write

Produces: application/json
put
/gift_certificate/gift_certificates/{gift_certificate_oid}

Update a gift certificate for this merchant account.

SDK Function Name: updateGiftCertificate

Parameters
Parameter Description Location Data Type Required
gift_certificate_oid path integer (int32) optional
gift_certificate Gift certificate body GiftCertificate required
Responses
Status Code Reason Response Model
200
 Successful response GiftCertificateResponse
400
 Bad Request 400
401
 Unauthorized 401
410
 Authorized Application Disabled 410
429
 Too Many Requests 429
500
 Server Side 500 
using com.ultracart.admin.v2.Api;
using com.ultracart.admin.v2.Model;

namespace SdkSample.gift_certificate
{
    // ReSharper disable once ClassNeverInstantiated.Global
    public class UpdateGiftCertificate
    {
        // uncomment to run.  C# projects can only have one main.
        // public static void Main()
        // {
        //     var giftCertificate = UpdateGiftCertificateCall();
        //     Utility.DumpObject(giftCertificate, "Gift Certificate");
        // }

        // ReSharper disable once MemberCanBePrivate.Global
        public static GiftCertificate UpdateGiftCertificateCall()
        {
            var api = new GiftCertificateApi(Constants.API_KEY);
            
            const int giftCertificateOid = 676713;
            
            var gcResponse = api.GetGiftCertificateByOid(giftCertificateOid);
            var giftCertificate = gcResponse.GiftCertificate;
            giftCertificate.Email = "perry@ultracart.com";
            

            // update does not take an expansion variable.  it will return the entire object by default.
            gcResponse = api.UpdateGiftCertificate(giftCertificateOid, giftCertificate);
            return gcResponse.GiftCertificate;
        }
    }
}

package gift_certificate;

import com.ultracart.admin.v2.GiftCertificateApi;
import com.ultracart.admin.v2.models.GiftCertificate;
import com.ultracart.admin.v2.models.GiftCertificateResponse;
import common.Constants;
import common.JSON;

public class UpdateGiftCertificate{

  public static void main(String ... args) throws Exception {

    GiftCertificateApi giftCertificateApi = new GiftCertificateApi(Constants.API_KEY, Constants.VERIFY_SSL_FLAG, Constants.DEBUG_MODE);

    int giftCertificateOid = 676713;

    // by_oid does not take an expansion variable.  it will return the entire object by default.
    GiftCertificateResponse gcResponse = giftCertificateApi.getGiftCertificateByOid(giftCertificateOid);
    GiftCertificate giftCertificate = gcResponse.getGiftCertificate();

    giftCertificate.setEmail("support@ultracart.com");
    gcResponse = giftCertificateApi.updateGiftCertificate(giftCertificateOid, giftCertificate);
    giftCertificate = gcResponse.getGiftCertificate();

    System.out.println(JSON.toJSON(giftCertificate));

  }

}

var ucApi = require('ultra_cart_rest_api_v2');
const { apiClient } = require('../api.js');

var giftCertificateApi = new ucApi.GiftCertificateApi(apiClient);

let giftCertificateOid = 676713;


// by_oid does not take an expansion variable.  it will return the entire object by default.
giftCertificateApi.getGiftCertificateByOid(giftCertificateOid, 
    function(error, data, response){
        let giftCertificate = data.gift_certificate;    

        // now update the email
        giftCertificate.email = 'perry@ultracart.com';
        giftCertificateApi.updateGiftCertificate(giftCertificateOid, giftCertificate,
            function(error, data, response){
                let updatedCertificate = data.gift_certificate;    
                console.log('updatedCertificate', updatedCertificate);
            });

    });

<?php
require_once '../vendor/autoload.php';
require_once '../samples.php';

$gift_certificate_api = Samples::getGiftCertificateApi();

$gift_certificate_oid = 676713;

// by_oid does not take an expansion variable.  it will return the entire object by default.
$api_response = $gift_certificate_api->getGiftCertificateByOid($gift_certificate_oid);
$gift_certificate = $api_response->getGiftCertificate();

$gift_certificate->setEmail("perry@ultracart.com");
$api_response = $gift_certificate_api->updateGiftCertificate($gift_certificate_oid, $gift_certificate);

echo '<html lang="en"><body><pre>';
var_dump($api_response);
var_dump($api_response->getGiftCertificate());
echo '</pre></body></html>';




# update a gift certificate

from ultracart.apis import GiftCertificateApi
from ultracart.rest import ApiException
from pprint import pprint
from samples import api_client

api_instance = GiftCertificateApi(api_client())

try:

    gift_certificate_oid = 676713

    # by_oid does not take an expansion variable.  it will return the entire object by default.
    gc_response = api_instance.get_gift_certificate_by_oid(gift_certificate_oid)
    gift_certificate = gc_response.gift_certificate

    gift_certificate.email = 'support@ultracart.com'

    gc_response = api_instance.update_gift_certificate(gift_certificate_oid, gift_certificate)
    gift_certificate = gc_response.gift_certificate

    pprint(gift_certificate)

except ApiException as e:
    print("Exception when calling GiftCertificateApi->update_gift_certificate: %s\n" % e)


require 'json'
require 'yaml'
require 'ultracart_api'
require_relative '../constants'

api = UltracartClient::GiftCertificateApi.new_using_api_key(Constants::API_KEY, Constants::VERIFY_SSL, Constants::DEBUG_MODE)

# grab a gift certificate that already exists.  use the create script if needed.
gift_certificate_oid = 676_713

api_response = api.get_gift_certificate_by_oid(gift_certificate_oid)
gift_certificate = api_response.gift_certificate

gift_certificate.email = 'perry@ultracart.com'

# by_code does not take an expansion variable.  it will return the entire object by default.
api_response = api.update_gift_certificate(gift_certificate_oid, gift_certificate)
gift_certificate = api_response.gift_certificate

puts gift_certificate.to_yaml


// I'm using the .js extension here so this file can be run stand-alone using node. Normally, there would be no extension.
import { giftCertificateApi } from '../api.js';
// import { giftCertificateApi } from '../api';
import { GetGiftCertificateByOidRequest, UpdateGiftCertificateRequest } from 'ultracart_rest_api_v2_typescript';



let giftCertificateOid = 676813;


// by_oid does not take an expansion variable.  it will return the entire object by default.
let getGiftCertificateByOidRequest: GetGiftCertificateByOidRequest = {
    giftCertificateOid: giftCertificateOid
};
let gcResponse = await giftCertificateApi.getGiftCertificateByOid(getGiftCertificateByOidRequest);
let giftCertificate = gcResponse.gift_certificate;

if(giftCertificate){
    giftCertificate.email = 'perry@ultracart.com';
    let updateGiftCertificateRequest: UpdateGiftCertificateRequest = {
        giftCertificateOid: giftCertificateOid,
        giftCertificate: giftCertificate
    };

    gcResponse = await giftCertificateApi.updateGiftCertificate(updateGiftCertificateRequest);
    giftCertificate = gcResponse.gift_certificate;
            
    console.log(giftCertificate);
    
} else {
    console.log('Gift certificate was not found on the UltraCart system.  Perhaps you are running a demo and have not created a certificate yet?  Be sure to change the giftCertificateOid to your own cert.');
}

Add a gift certificate ledger entry

Permissions:
  • gift_certificate_write

Produces: application/json
post
/gift_certificate/gift_certificates/{gift_certificate_oid}/ledger_entry

Adds a ledger entry for this gift certificate.

SDK Function Name: addGiftCertificateLedgerEntry

Parameters
Parameter Description Location Data Type Required
gift_certificate_oid path integer (int32) optional
gift_certificate_ledger_entry Gift certificate ledger entry body GiftCertificateLedgerEntry required
Responses
Status Code Reason Response Model
200
 Successful response GiftCertificateResponse
400
 Bad Request 400
401
 Unauthorized 401
410
 Authorized Application Disabled 410
429
 Too Many Requests 429
500
 Server Side 500 
using System;
using com.ultracart.admin.v2.Api;
using com.ultracart.admin.v2.Model;

namespace SdkSample.gift_certificate
{
    // ReSharper disable once ClassNeverInstantiated.Global
    public class AddGiftCertificateLedgerEntry
    {
        // uncomment to run.  C# projects can only have one main.
        // public static void Main()
        // {
        //     var giftCertificate = AddGiftCertificateLedgerEntryCall();
        //     Utility.DumpObject(giftCertificate, "Gift Certificate");
        // }

        // ReSharper disable once MemberCanBePrivate.Global
        public static GiftCertificate AddGiftCertificateLedgerEntryCall()
        {
            var api = new GiftCertificateApi(Constants.API_KEY);
            
            const int giftCertificateOid = 676713;
            
            GiftCertificateLedgerEntry ledgerEntry = new GiftCertificateLedgerEntry()
            {
                Amount = new Decimal(-15.35),  // this is the change amount in the gift certificate.  this is not a balance.  it will be subtracted from it.
                Description = "Customer bought something over the counter using this gift certificate.",
                EntryDts = DateTime.UtcNow.ToString("s", System.Globalization.CultureInfo.InvariantCulture),
                GiftCertificateLedgerOid = 0,  // the system will assign an oid.  do not assign one here.
                GiftCertificateOid = giftCertificateOid,  // this is an existing gift certificate oid.  I created it using createGiftCertificate.ts
                ReferenceOrderId = "BLAH-12345" // if this ledger entry is related to an order, add it here, else use null.                
            };

            // add ledger entry does not take an expansion variable.  it will return the entire object by default.
            var gcResponse = api.AddGiftCertificateLedgerEntry(giftCertificateOid, ledgerEntry);
            return gcResponse.GiftCertificate;
        }
    }
}

package gift_certificate;

import com.ultracart.admin.v2.GiftCertificateApi;
import com.ultracart.admin.v2.models.GiftCertificate;
import com.ultracart.admin.v2.models.GiftCertificateLedgerEntry;
import com.ultracart.admin.v2.models.GiftCertificateResponse;
import common.Constants;
import common.JSON;
import org.joda.time.DateTime;
import org.joda.time.format.DateTimeFormatter;
import org.joda.time.format.ISODateTimeFormat;

import java.math.BigDecimal;

public class AddGiftCertificateLedgerEntry{

  public static void main(String ... args) throws Exception {

    GiftCertificateApi giftCertificateApi = new GiftCertificateApi(Constants.API_KEY, Constants.VERIFY_SSL_FLAG, Constants.DEBUG_MODE);
    DateTimeFormatter fmt = ISODateTimeFormat.dateTimeNoMillis();

    int giftCertificateOid = 676713;

    GiftCertificateLedgerEntry ledgerEntry = new GiftCertificateLedgerEntry();
    ledgerEntry.setAmount(new BigDecimal("-15.55")); // this is the change amount in the gift certificate.  this is not a balance.  it will be subtracted from it.
    ledgerEntry.setDescription("Debit using Java SDK");
    ledgerEntry.setEntryDts(fmt.print(DateTime.now()));
    ledgerEntry.setGiftCertificateLedgerOid(0); // the system will assign an oid.  do not assign one here.
    ledgerEntry.setGiftCertificateOid(giftCertificateOid); // this is an existing gift certificate oid.  I created it using createGiftCertificate.ts
    ledgerEntry.setReferenceOrderId("BLAH-54321"); // if this ledger entry is related to an order, add it here, else use null.

    // add ledger does not take an expansion variable.  it will return the entire object by default.
    GiftCertificateResponse gcResponse = giftCertificateApi.addGiftCertificateLedgerEntry(giftCertificateOid, ledgerEntry);
    GiftCertificate giftCertificate = gcResponse.getGiftCertificate();

    System.out.println(JSON.toJSON(giftCertificate));

  }

}

var ucApi = require('ultra_cart_rest_api_v2');
const { apiClient } = require('../api.js');
var luxon = require('luxon');

var giftCertificateApi = new ucApi.GiftCertificateApi(apiClient);

let giftCertificateOid = 676813;
let ledgerEntry = new ucApi.GiftCertificateLedgerEntry();

ledgerEntry.amount = -65.35;  // this is the change amount in the gift certificate.  this is not a balance.  it will be subtracted from it.
ledgerEntry.description = "Customer bought something over the counter using this gift certificate.";
ledgerEntry.entry_dts = luxon.DateTime.now().setZone('America/New_York').toISO();
ledgerEntry.gift_certificate_ledger_oid = 0;  // the system will assign an oid.  do not assign one here.
ledgerEntry.gift_certificate_oid = giftCertificateOid  // this is an existing gift certificate oid.  I created it using createGiftCertificate.ts
ledgerEntry.reference_order_id = 'BLAH-12345'; // if this ledger entry is related to an order, add it here, else use null.


// add ledger entry does not take an expansion variable.  it will return the entire object by default.
giftCertificateApi.addGiftCertificateLedgerEntry(giftCertificateOid, ledgerEntry, 
    function(error, data, response){
        let giftCertificate = data.gift_certificate;    
        console.log('giftCertificate', giftCertificate);
    });

<?php

use ultracart\v2\models\GiftCertificateCreateRequest;

require_once '../vendor/autoload.php';
require_once '../samples.php';

$gift_certificate_api = Samples::getGiftCertificateApi();

$gift_certificate_oid = 676813;

$entry_dts = new DateTime('now');

$ledger_entry = new \ultracart\v2\models\GiftCertificateLedgerEntry();
$ledger_entry->setAmount(-10.15); // this is the change amount in the gift certificate.  this is not a balance.  it will be subtracted from it.
$ledger_entry->setDescription("Customer bought something over the counter");
$ledger_entry->setReferenceOrderId('BLAH-12345'); // if this ledger entry is related to an order, add it here, else use null.
$ledger_entry->setEntryDts($entry_dts->format('c')); // Must be ISO8601 format
$ledger_entry->setGiftCertificateLedgerOid(0);  // the system will assign an oid.  do not assign one here.
$ledger_entry->setGiftCertificateOid($gift_certificate_oid);  // this is an existing gift certificate oid.  I created it using createGiftCertificate.ts


// ledger entry does not take an expansion variable.  it will return the entire object by default.
$api_response = $gift_certificate_api->addGiftCertificateLedgerEntry($gift_certificate_oid, $ledger_entry);

echo '<html lang="en"><body><pre>';
var_dump($api_response);
var_dump($api_response->getGiftCertificate());
echo '</pre></body></html>';




#  add a gift certificate ledger entry.  this is how you affect the remaining balance.
from ultracart.apis import GiftCertificateApi
from ultracart.model.gift_certificate_ledger_entry import GiftCertificateLedgerEntry
from ultracart.rest import ApiException
from pprint import pprint
from samples import api_client
from datetime import datetime

api_instance = GiftCertificateApi(api_client())

try:

    amount = -65.35  # this is the change in the gc.  this is not a balance.  it will be subtracted from it.
    description = "Customer bought something."
    entry_dts = datetime.now().astimezone().isoformat('T', 'milliseconds')
    gift_certificate_oid = 676713  # this is an existing gift certificate oid.  I created it using create_gift_certificate.py
    reference_order_id = 'BLAH-12345'  # if this ledger entry is related to an order, add it here, else use null.
    ledger_entry = GiftCertificateLedgerEntry(amount=amount,
                                              description=description,
                                              entry_dts=entry_dts,
                                              gift_certificate_oid=gift_certificate_oid,
                                              reference_order_id=reference_order_id)

    # create does not take an expansion variable.  it will return the entire object by default.
    gc_response = api_instance.add_gift_certificate_ledger_entry(gift_certificate_oid, ledger_entry)
    gift_certificate = gc_response.gift_certificate

    pprint(gift_certificate)

except ApiException as e:
    print("Exception when calling GiftCertificateApi->add_gift_certificate_ledger_entry: %s\n" % e)


# frozen_string_literal: true

require 'date'
require 'json'
require 'yaml'
require 'ultracart_api'
require_relative '../constants'

api = UltracartClient::GiftCertificateApi.new_using_api_key(Constants::API_KEY, Constants::VERIFY_SSL, Constants::DEBUG_MODE)

gift_certificate_oid = 676_713

ledger_entry = UltracartClient::GiftCertificateLedgerEntry.new

ledger_entry.amount = -15.35  # this is the change amount in the gift certificate.
# amount is not a balance.  it will be subtracted from it.
ledger_entry.description = 'Customer bought something over the counter'
ledger_entry.entry_dts = DateTime.now
ledger_entry.gift_certificate_ledger_oid = 0 # the system will assign an oid.  do not assign one here.
ledger_entry.gift_certificate_oid = gift_certificate_oid # this is an existing gift certificate oid.
# The existing gift certificate was created using create_gift_certificate.rb
ledger_entry.reference_order_id = 'BLAH-12345'
# if this ledger entry is related to an order, add it here, else use null.

# add ledger entry does not take an expansion variable.  it will return the entire object by default.
api_response = api.add_gift_certificate_ledger_entry(gift_certificate_oid, ledger_entry)
gift_certificate = api_response.gift_certificate

puts gift_certificate.to_yaml


// I'm using the .js extension here so this file can be run stand-alone using node. Normally, there would be no extension.
import { giftCertificateApi } from '../api.js';
// import { giftCertificateApi } from '../api';

import { AddGiftCertificateLedgerEntryRequest, GiftCertificateLedgerEntry } from 'ultracart_rest_api_v2_typescript';
import { DateTime } from 'luxon';


let giftCertificateOid = 676813;

let ledgerEntry: GiftCertificateLedgerEntry = {};

ledgerEntry.amount = -65.35;  // this is the change amount in the gift certificate.  this is not a balance.  it will be subtracted from it.
ledgerEntry.description = "Customer bought something over the counter using this gift certificate.";
ledgerEntry.entry_dts = DateTime.now().setZone('America/New_York').toISO();
ledgerEntry.gift_certificate_ledger_oid = 0;  // the system will assign an oid.  do not assign one here.
ledgerEntry.gift_certificate_oid = giftCertificateOid  // this is an existing gift certificate oid.  I created it using createGiftCertificate.ts
ledgerEntry.reference_order_id = 'BLAH-12345'; // if this ledger entry is related to an order, add it here, else use null.


const addGiftCertificateLedgerEntryRequest: AddGiftCertificateLedgerEntryRequest = {
    giftCertificateOid: giftCertificateOid,
    giftCertificateLedgerEntry: ledgerEntry
};

// add ledger entry method does not take an expansion variable.  it will return the entire object by default.
let gcResponse = await giftCertificateApi.addGiftCertificateLedgerEntry(addGiftCertificateLedgerEntryRequest);
let giftCertificate = gcResponse.gift_certificate;

console.log(giftCertificate);

Error

Attributes
Name Data Type Description
developer_message string A technical message meant to be read by a developer
error_code string HTTP status code
more_info string Additional information often a link to additional documentation
object_id string Object id that the error is associated with
user_message string An end-user friendly message suitable for display to the customer

ErrorResponse

Attributes
Name Data Type Description
error Error Error object if unsuccessful
metadata ResponseMetadata Meta-data about the response such as payload or paging information
success boolean Indicates if API call was successful
warning Warning Warning object if a non-fatal issue or side-effect occurs

GiftCertificate

Attributes
Name Data Type Description
activated boolean True if this gift certificate is activated and ready to apply to purchases.
code (read only) string The code used by the customer to purchase against this gift certificate.
customer_profile_oid (read only) integer (int32) This is the customer profile oid associated with this internally managed gift certificate.
deleted boolean True if this gift certificate was deleted.
email string(100) Email of the customer associated with this gift certificate.
expiration_dts string (dateTime) Expiration date time.
gift_certificate_oid (read only) integer (int32) Gift certificate oid.
internal (read only) boolean This is an internally managed gift certificate associated with the loyalty cash rewards program.
ledger_entries (read only) array of GiftCertificateLedgerEntry A list of all ledger activity for this gift certificate.
merchant_id string Merchant Id
merchant_note string A list of all ledger activity for this gift certificate.
original_balance (read only) number Original balance of the gift certificate.
reference_order_id (read only) string The order used to purchase this gift certificate. This value is ONLY set during checkout when a certificate is purchased, not when it is used. Any usage is recorded in the ledger
remaining_balance (read only) number The remaining balance on the gift certificate. This is never set directly, but calculated from the ledger. To change the remaining balance, add a ledger entry.

GiftCertificateCreateRequest

Attributes
Name Data Type Description
amount number Initial amount of this gift certificate.
email string The email address (customer/owner) associated with this gift certificate.
expiration_dts string (dateTime) Expiration date time.
initial_ledger_description string A brief description of how and/or why this gift certificate was created.
merchant_note string Any internal details you wish to record about this gift certificate.

GiftCertificateLedgerEntry

Attributes
Name Data Type Description
amount number The amount of the activity.
description string(50) Description of what this ledger entry is used.
entry_dts string (dateTime) Date time of this ledger activity.
gift_certificate_ledger_oid integer (int32) Gift certificate ledger oid is a primary key for this object, used internally.
gift_certificate_oid integer (int32) Gift certificate oid.
reference_order_id string The order id if this gift certificate was used as part of the payment.

GiftCertificateQuery

Attributes
Name Data Type Description
code string Gift certificate code
email string Email address of this gift certificate
expiration_dts_end string (dateTime) Expiration date end
expiration_dts_start string (dateTime) Expiration date start
original_balance_end number Original balance end
original_balance_start number Original balance start
reference_order_id string Gift certificate reference order id
remaining_balance_end number Remaining balance end
remaining_balance_start number Remaining balance start

GiftCertificateResponse

Attributes
Name Data Type Description
error Error Error object if unsuccessful
gift_certificate GiftCertificate
metadata ResponseMetadata Meta-data about the response such as payload or paging information
success boolean Indicates if API call was successful
warning Warning Warning object if a non-fatal issue or side-effect occurs

GiftCertificatesResponse

Attributes
Name Data Type Description
error Error Error object if unsuccessful
gift_certificates array of GiftCertificate
metadata ResponseMetadata Meta-data about the response such as payload or paging information
success boolean Indicates if API call was successful
warning Warning Warning object if a non-fatal issue or side-effect occurs

ResponseMetadata

Attributes
Name Data Type Description
payload_name string Payload name
result_set ResultSet Result set

ResultSet

Attributes
Name Data Type Description
count integer (int32) Number of results in this set
limit integer (int32) Maximum number of results that can be returned in a set
more boolean True if there are more results to query
next_offset integer (int32) The next offset that you should query to retrieve more results
offset integer (int32) Offset of this result set (zero based)
total_records integer (int32) The total number of records in the result set. May be null if the number is not known and the client should continue iterating as long as more is true.

Warning

Attributes
Name Data Type Description
more_info string Additional information often a link to additional documentation
warning_message string A technical message meant to be read by a developer

400
Status Code 400: bad request input such as invalid json

Headers
Name Data Type Description
UC-REST-ERROR string Contains human readable error message
Response
Name Data Type
body ErrorResponse

401
Status Code 401: invalid credentials supplied

Headers
Name Data Type Description
UC-REST-ERROR string Contains human readable error message
Response
Name Data Type
body ErrorResponse

410
Status Code 410: Your authorized application has been disabled by UltraCart

Headers
Name Data Type Description
UC-REST-ERROR string Contains human readable error message
Response
Name Data Type
body ErrorResponse

429
Status Code 429: you have exceeded the allowed API call rate limit for your application.

Headers
Name Data Type Description
UC-REST-ERROR string Contains human readable error message
Response
Name Data Type
body ErrorResponse

500
Status Code 500: any server side error. the body will contain a generic server error message

Headers
Name Data Type Description
UC-REST-ERROR string Contains human readable error message
Response
Name Data Type
body ErrorResponse